OneSignal is Agent-Ready to agents.
Discry independently scored how well an AI agent can discover and understand the OneSignal API from what’s public — not whether it’s usable. Below: every signal we checked, what’s costing the score, and what to change.
SCORED UNDER RUBRIC 1.2 · A full re-launch under Discry Score 2.5 — a new behavioral instrument, not comparable to these scores — is in progress.
Discovery
45% of score · 95/100Comprehension
55% of score · 100/100What we found
- An agent looking for OneSignal's machine-readable contract finds it immediately: an official, publicly accessible OpenAPI spec (github.com/OneSignal/api, api.json) that OneSignal itself uses to generate every server SDK — so the spec and the live API stay in lockstep.
- Every documentation and API-reference page is retrievable as clean markdown via a .md suffix (content negotiation), and each page opens with a pointer to the llms.txt index — an agent can traverse the entire corpus without parsing a single JavaScript-rendered HTML page.
- The rate-limits and error-handling reference is best-in-class for agent self-correction: an agent that hits a 429 is told the exact JSON error shape, to read Retry-After, to reuse the same idempotency_key, and is given a retry-decision table plus worked app-disablement scenarios — it can recover autonomously instead of failing blind.
- Discovery signals are fully saturated: robots.txt explicitly permits AI crawlers (Content-Signal ai-train=yes), a valid .well-known/mcp.json advertises an HTTP MCP endpoint, official AGENTS.md files ship in multiple OneSignal SDK repos, and the API is listed across MCP registries (Glama, Smithery, PulseMCP).
- Comprehension is uniformly strong: endpoint docs are task-oriented, examples use realistic values (real UUID subscription IDs, E.164 numbers, copy-paste curl, multi-language content), naming is consistently snake_case, and capability boundaries (per-request caps of 20,000 recipients / 200 filter entries, targeting-method exclusivity, filter performance tiers) are stated up front.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Maintain the OpenAPI spec's freshness cadence — the public api.json in github.com/OneSignal/api last shipped substantive commits some time ago; keep it version-bumped in step with new endpoints so SDK-generating and spec-reading agents never drift from the live API.
- 02Promote the .well-known/mcp.json endpoint to a stable production host — it currently points at a Mintlify preview-style URL (onesignal.main-kill-isr.mintlify.me/mcp); a branded, stable MCP URL removes any risk of an agent resolving a transient endpoint.
- 03Add a top-level /openapi.json (or /openapi.yaml) redirect on documentation.onesignal.com so agents probing the conventional spec path resolve the GitHub-hosted spec without a web search.
- 04Consider trimming llms.txt to an API-first subset or shipping a dedicated api-llms.txt — the current index (~20K tokens, ~325 links) is well-structured but weights product/marketing docs alongside API reference, so an API-focused agent spends tokens filtering.
Execution coverage · INFORMATIONAL, UNSCORED
Whether an agent can actually complete a call and recover from errors is the deeper Audit layer — documented here, but not part of the Discry Score.
Execution characteristics are documented to an exceptional depth. Auth uses App-level and Organization-level API keys (Authorization: Key header) with IP-allowlisting support; the 403 troubleshooting guide distinguishes wrong-key-type from permission errors. Errors return a machine-parseable JSON body ({"errors": [...]}), with a full retry decision table mapping 429/5xx/timeout/400/401 to retry behavior. Rate limits are specified per-endpoint and per-plan (150 vs 6,000 req/sec/app) with a Retry-After header, and idempotency_key usage is documented for safe retries. This is claimed behavior only — live testing requires a full Discry Audit.