ax 0.10.2 → 0.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +26 -19
- package/dist/api/agent-files.d.ts +1 -1
- package/dist/api/deep-journey.d.ts +30 -2
- package/dist/api/key-destination.d.ts +19 -0
- package/dist/api/platform.d.ts +14 -0
- package/dist/api/shared.d.ts +9 -0
- package/dist/api/skills.d.ts +19 -0
- package/dist/contract/index.d.ts +1 -0
- package/dist/contract/types.gen.d.ts +619 -46
- package/dist/contract/version.d.ts +1 -1
- package/dist/env.d.ts +24 -0
- package/dist/index.cjs +160 -22
- package/dist/index.js +160 -22
- package/dist/main.cjs +227 -79
- package/package.json +3 -3
|
@@ -56,6 +56,13 @@ export interface paths {
|
|
|
56
56
|
*/
|
|
57
57
|
get: operations["getScore"];
|
|
58
58
|
};
|
|
59
|
+
"/api/deep-checks/{domain}": {
|
|
60
|
+
/**
|
|
61
|
+
* Poll deep checks for a scan
|
|
62
|
+
* @description Returns checks and completion state for the caller's assigned scan. Pass the scanId from the original response to keep reading that scan after an assignment changes. With scanId, domain can be the URL-encoded exact MCP endpoint. Responses are never cached.
|
|
63
|
+
*/
|
|
64
|
+
get: operations["getDeepChecks"];
|
|
65
|
+
};
|
|
59
66
|
"/api/badge/{domain}": {
|
|
60
67
|
/**
|
|
61
68
|
* Get SVG badge for a domain
|
|
@@ -63,10 +70,17 @@ export interface paths {
|
|
|
63
70
|
*/
|
|
64
71
|
get: operations["getBadge"];
|
|
65
72
|
};
|
|
73
|
+
"/api/ranker/releases/{version}/rules": {
|
|
74
|
+
/**
|
|
75
|
+
* Read the rules for a published scoring version
|
|
76
|
+
* @description Returns the scored checks, layer weights, grade thresholds and score formula for the requested version. A frozen version returns exactly the rules it was frozen with. Before managed publication, the current default and explicitly available legacy scoring versions are readable with publishedAt set to null. After managed publication, unpublished candidates are not public. No authentication required; responses use Cache-Control: no-store and Access-Control-Allow-Origin: *.
|
|
77
|
+
*/
|
|
78
|
+
get: operations["getScoringRules"];
|
|
79
|
+
};
|
|
66
80
|
"/api/checks": {
|
|
67
81
|
/**
|
|
68
82
|
* Get the complete catalog of scanner checks
|
|
69
|
-
* @description Returns every check the ora scanner can run - stable id, scored layer, max score, applicability, eligible scan kinds, tier, maturity, and fix guidance per check, plus the four scored layers with their weights. Check ids are stable: gate CI on an explicit id list, not on tiers (the required set can grow on a minor version). Ids are also what POST /api/scan/checks takes, and every check carries a `beta` boolean for building check pickers - a beta check runs but cannot affect any score. The
|
|
83
|
+
* @description Returns every check the ora scanner can run - stable id, scored layer, max score, applicability, eligible scan kinds, tier, maturity, and fix guidance per check, plus the four scored layers with their weights. Check ids are stable: gate CI on an explicit id list, not on tiers (the required set can grow on a minor version). Ids are also what POST /api/scan/checks takes, and every check carries a `beta` boolean for building check pickers - a beta check runs but cannot affect any score. The catalog follows the public scoring version or the partner API key's assigned version; scoringVersion and rulesUrl identify its rules. One optional parameter: `?include=essentials` adds `essentialsTier`, `essentialsBonusOnly`, and `essentialsExcluded` (the essentials-model classification; excluded checks are ignored by that model outright) to every check; without it those fields are omitted. Sends Access-Control-Allow-Origin: *. Keyed or managed-release responses use private, no-store; anonymous legacy responses are CDN-cached for 1 hour. Rate limited to 60 requests per minute per IP - returns 429 with a Retry-After header if exceeded.
|
|
70
84
|
*/
|
|
71
85
|
get: operations["listChecks"];
|
|
72
86
|
};
|
|
@@ -94,14 +108,14 @@ export interface paths {
|
|
|
94
108
|
"/api/ard/search": {
|
|
95
109
|
/**
|
|
96
110
|
* Search agentic resources (Agentic Resource Discovery)
|
|
97
|
-
* @description Runs an Agentic Resource Discovery (ARD) search over ora's catalog of agent-ready resources. Returns resources ranked by relevance to a free-text query, with optional field filters and federation control. The per-result `score` is
|
|
111
|
+
* @description Runs an Agentic Resource Discovery (ARD) search over ora's catalog of agent-ready resources. Returns resources ranked by relevance to a free-text query, with optional field filters and federation control. The per-result `score` is pure relevance (0-100): match quality for the query, never a trust or readiness rating. Results are ordered by relevance with agent-readiness reordering close matches, so `score` need not decrease down the list; the readiness itself is in `oraScorecard` and GET /api/score/{domain}. Rate limited to 30 requests per minute per IP - returns 429 if exceeded.
|
|
98
112
|
*/
|
|
99
113
|
post: operations["ardSearch"];
|
|
100
114
|
};
|
|
101
115
|
"/api/ard/explore": {
|
|
102
116
|
/**
|
|
103
117
|
* Faceted exploration of agentic resources (Agentic Resource Discovery)
|
|
104
|
-
* @description Returns facet aggregations (counts per field value) for an Agentic Resource Discovery (ARD) result set. Use this to build filter UIs over the ARD catalog. An optional query narrows the set before faceting. Rate limited to 30 requests per minute per IP - returns 429 if exceeded.
|
|
118
|
+
* @description Returns facet aggregations (counts per field value) for an Agentic Resource Discovery (ARD) result set. Use this to build filter UIs over the ARD catalog. A `type` bucket's value is the raw media type, so it can be used as a filter value as-is. An optional query narrows the set before faceting: with text, the set is exactly what POST /api/ard/search matches for the same text and filter; without it, the whole index narrowed by the filter. Rate limited to 30 requests per minute per IP - returns 429 if exceeded.
|
|
105
119
|
*/
|
|
106
120
|
post: operations["ardExplore"];
|
|
107
121
|
};
|
|
@@ -143,7 +157,7 @@ export interface paths {
|
|
|
143
157
|
"/api/agent-files/{domain}": {
|
|
144
158
|
/**
|
|
145
159
|
* Draft a domain's own agent discovery files (ard.json, ai-catalog.json, poppy.json)
|
|
146
|
-
* @description Drafts the agent discovery files a domain publishes about itself: /.well-known/ard.json (Agentic Resource Discovery), /.well-known/ai-catalog.json (the same catalog at the AI Catalog Standard's path) and /.well-known/poppy.json (Personal Agent Protocol,
|
|
160
|
+
* @description Drafts the agent discovery files a domain publishes about itself: /.well-known/ard.json (Agentic Resource Discovery), /.well-known/ai-catalog.json (the same catalog at the AI Catalog Standard's path) and /.well-known/poppy.json (Personal Agent Protocol 1.0, the latest published version). Built from what ora already holds for the domain - no live crawl - so a domain ora never scanned still gets a valid minimal set (a catalog listing its website, a poppy.json for signed-out browsing) with scannedAt null. Every catalog entry is anchored to the domain itself (urn:air:<domain>:..., identity https://<domain>), never to ora, and carries only https URLs on the domain or its subdomains: anything the scan saw on another host is named in the file's notes instead. MCP servers are listed by their server card (the card the scan found, else the reserved <server-url>/server-card location, which the notes ask the owner to serve). The poppy.json is the minimal valid document; what ora saw that a fuller one could name (an OAuth issuer, MCP servers, an OpenAPI description) is listed in that file's notes. Pass ?include= for llms.txt, an edit of the site's robots.txt, an RFC 9727 api-catalog and draft MCP server cards. Review every file before publishing it. A leading www. is dropped, and any spelling other than the canonical domain answers 308 to /api/agent-files/<domain>. Sends Access-Control-Allow-Origin: * and is CDN-cached. Rate limited to 60 requests per minute per IP - returns 429 if exceeded. Also used by the generator page at directory.ora.ai/generate and by `npx ax generate-files <domain>`.
|
|
147
161
|
*/
|
|
148
162
|
get: operations["generateAgentFiles"];
|
|
149
163
|
};
|
|
@@ -171,14 +185,14 @@ export interface paths {
|
|
|
171
185
|
"/api/journey/runs/{id}": {
|
|
172
186
|
/**
|
|
173
187
|
* Get a journey run record (non-streaming)
|
|
174
|
-
* @description Returns the run record by id. While the run executes, `status` is 'running' - open the stream or poll. Once finished and persisted, `status` is 'succeeded' and the body carries `verdict`, `step_count` (billable steps - the same counter run pricing uses), and the full `result` (trajectory + insight + signals). `status` 'failed' is terminal with no result. `result` is present iff status is 'succeeded'.
|
|
188
|
+
* @description Returns the run record by id. While the run executes, `status` is 'running' - open the stream or poll. Once finished and persisted, `status` is 'succeeded' and the body carries `verdict`, `step_count` (billable steps - the same counter run pricing uses), `flags` (two notes beside the verdict that never change it: `blocked` when the site refused the agent, `answered_from_memory` when half or more of the answer came from the model's memory), and the full `result` (trajectory + insight + signals). `status` 'failed' is terminal with no result. `result` is present iff status is 'succeeded'. `next_action` names the one request to send next: the run's stream while it is running, and for 15 minutes after it failed, since reopening it reconnects a run that only lost its connection. A succeeded run carries none, and neither does one that failed longer ago, which is final.
|
|
175
189
|
*/
|
|
176
190
|
get: operations["getJourneyRun"];
|
|
177
191
|
};
|
|
178
192
|
"/api/journey/domains/{host}": {
|
|
179
193
|
/**
|
|
180
194
|
* Get or create a domain's agent journey
|
|
181
|
-
* @description Returns the agent journey for a domain, running one only if there is not one already. Send only the domain and no body: ora selects the intent and the agent. Requires an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora); without one, 401 PARTNER_KEY_REQUIRED. 200 means nothing was dispatched and an existing run answered, either finished (carrying its `result`) or still running (open `stream_url` to watch it). 201 means a new run was dispatched. Branch on `dispatched`. Two response views (see the `view` parameter): `graph` (JourneyDomainRunGraph, the default - `result` narrowed to what drawing the journey needs) and `full` (JourneyDomainRun, the complete projection, on `?view=full`). A finished run is served indefinitely; `run_age_seconds` gives its age. There is no per-caller rate limit on this endpoint. Each domain is capped at 100 runs per rolling 24h, and one domain cannot start two runs at once - both are per-domain, neither limits how many domains you may ask for or how fast.
|
|
195
|
+
* @description Returns the agent journey for a domain, running one only if there is not one already. Send only the domain and no body: ora selects the intent and the agent. Requires an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora); without one, 401 PARTNER_KEY_REQUIRED. 200 means nothing was dispatched and an existing run answered, either finished (carrying its `result`) or still running (open `stream_url` to watch it). 201 means a new run was dispatched. Branch on `dispatched`. Two response views (see the `view` parameter): `graph` (JourneyDomainRunGraph, the default - `result` narrowed to what drawing the journey needs) and `full` (JourneyDomainRun, the complete projection, on `?view=full`). A finished run is served indefinitely; `run_age_seconds` gives its age. There is no per-caller rate limit on this endpoint, except a daily or monthly journey usage limit when the key carries one. Each domain is capped at 100 runs per rolling 24h, and one domain cannot start two runs at once - both are per-domain, neither limits how many domains you may ask for or how fast.
|
|
182
196
|
*/
|
|
183
197
|
post: operations["getOrCreateDomainJourney"];
|
|
184
198
|
};
|
|
@@ -203,6 +217,13 @@ export interface paths {
|
|
|
203
217
|
*/
|
|
204
218
|
get: operations["listJourneyAgents"];
|
|
205
219
|
};
|
|
220
|
+
"/api/usage": {
|
|
221
|
+
/**
|
|
222
|
+
* Read your partner API key's usage and usage limits
|
|
223
|
+
* @description Returns the calling key's own usage for the current period, per kind (scans, journeys) and per period (`day`, the calendar day in UTC, and `month`, the calendar month in UTC): how many new dispatches the key started since period_start, its limit, what remains, and when the count resets. Cached and stored answers are not counted. limit and remaining are null when the key has no limit for that kind; a key with no limit is never refused for usage. Requires an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora); the key is read from the token, so a caller can only see its own numbers. Every response carries Cache-Control: no-store. Rate limited to 60 requests per minute per key.
|
|
224
|
+
*/
|
|
225
|
+
get: operations["getKeyUsage"];
|
|
226
|
+
};
|
|
206
227
|
"/api/feedback/{domain}": {
|
|
207
228
|
/**
|
|
208
229
|
* Get agent feedback for a product
|
|
@@ -341,6 +362,11 @@ export interface components {
|
|
|
341
362
|
recommendation?: string;
|
|
342
363
|
/** @description Why this check does not apply to this product - it is skipped, not a deduction */
|
|
343
364
|
naReason?: string;
|
|
365
|
+
/**
|
|
366
|
+
* @description Present only on 'na' checks that DO apply but could not be checked: 'unverified' means a bot shield answered instead of the site, the server requires authentication, our request got no answer, or a source we query (such as web search) did not reply. Skipped, not deducted, like any 'na'. Absent on an 'na' means the check does not apply to this product.
|
|
367
|
+
* @enum {string}
|
|
368
|
+
*/
|
|
369
|
+
naKind?: "unverified";
|
|
344
370
|
};
|
|
345
371
|
AuditLayer: {
|
|
346
372
|
/** @description Layer id: discovery | accessibility | usability | payments (historical scans may carry retired ids) */
|
|
@@ -379,9 +405,25 @@ export interface components {
|
|
|
379
405
|
recommendation?: string;
|
|
380
406
|
/** @description Why this check does not apply to this product - it is skipped, not a deduction */
|
|
381
407
|
naReason?: string;
|
|
408
|
+
/**
|
|
409
|
+
* @description Present only on 'na' checks that DO apply but could not be checked: 'unverified' means a bot shield answered instead of the site, the server requires authentication, our request got no answer, or a source we query (such as web search) did not reply. Skipped, not deducted, like any 'na'. Absent on an 'na' means the check does not apply to this product.
|
|
410
|
+
* @enum {string}
|
|
411
|
+
*/
|
|
412
|
+
naKind?: "unverified";
|
|
382
413
|
})[];
|
|
383
414
|
};
|
|
384
415
|
AuditScanResult: {
|
|
416
|
+
/** @description Stable managed scan ID. Pass it when polling to keep reading this scan after release assignments change. */
|
|
417
|
+
scanId?: number;
|
|
418
|
+
/** @description Scoring rules version used for this result, independent of contractVersion. Absent when an older result has no recorded version. */
|
|
419
|
+
scoringVersion?: number;
|
|
420
|
+
/**
|
|
421
|
+
* Format: uri
|
|
422
|
+
* @description Machine-readable rules for scoringVersion. Absent when the scoring version is unknown.
|
|
423
|
+
*/
|
|
424
|
+
rulesUrl?: string;
|
|
425
|
+
/** @description Revision of the shared check code under scoringVersion: a result reads as scoringVersion.scoringRevision. A higher revision means a shared check fix that can move scores under the same rules. Absent when unknown, including results stored before release management. */
|
|
426
|
+
scoringRevision?: number;
|
|
385
427
|
domain: string;
|
|
386
428
|
name: string;
|
|
387
429
|
score: number;
|
|
@@ -509,6 +551,11 @@ export interface components {
|
|
|
509
551
|
recommendation?: string;
|
|
510
552
|
/** @description Why this check does not apply to this product - it is skipped, not a deduction */
|
|
511
553
|
naReason?: string;
|
|
554
|
+
/**
|
|
555
|
+
* @description Present only on 'na' checks that DO apply but could not be checked: 'unverified' means a bot shield answered instead of the site, the server requires authentication, our request got no answer, or a source we query (such as web search) did not reply. Skipped, not deducted, like any 'na'. Absent on an 'na' means the check does not apply to this product.
|
|
556
|
+
* @enum {string}
|
|
557
|
+
*/
|
|
558
|
+
naKind?: "unverified";
|
|
512
559
|
})[];
|
|
513
560
|
})[];
|
|
514
561
|
/** @description Actionable (fail/warning) checks ranked by ora: non-bonus first, then estimated uplift descending, capped at 6. Render verbatim - do not re-rank. */
|
|
@@ -539,7 +586,7 @@ export interface components {
|
|
|
539
586
|
* @description The contract version this payload conforms to. SemVer: a major means a response-envelope break - a stable field removed, renamed, or changed in meaning, or the default response format flipping - and is safe to pin. Additive changes and check-catalog membership changes ship on a minor. See docs/api.md -> Contract and versioning.
|
|
540
587
|
* @enum {string}
|
|
541
588
|
*/
|
|
542
|
-
contractVersion: "1.
|
|
589
|
+
contractVersion: "1.42.0";
|
|
543
590
|
/**
|
|
544
591
|
* @description Present only when this body is a stored result served by the freshness gate instead of a fresh scan. Absent on a live scan.
|
|
545
592
|
* @enum {boolean}
|
|
@@ -587,6 +634,17 @@ export interface components {
|
|
|
587
634
|
} | null;
|
|
588
635
|
};
|
|
589
636
|
AuditScoreResult: {
|
|
637
|
+
/** @description Stable managed scan ID. Pass it when polling to keep reading this scan after release assignments change. */
|
|
638
|
+
scanId?: number;
|
|
639
|
+
/** @description Scoring rules version used for this result, independent of contractVersion. Absent when an older result has no recorded version. */
|
|
640
|
+
scoringVersion?: number;
|
|
641
|
+
/**
|
|
642
|
+
* Format: uri
|
|
643
|
+
* @description Machine-readable rules for scoringVersion. Absent when the scoring version is unknown.
|
|
644
|
+
*/
|
|
645
|
+
rulesUrl?: string;
|
|
646
|
+
/** @description Revision of the shared check code under scoringVersion: a result reads as scoringVersion.scoringRevision. A higher revision means a shared check fix that can move scores under the same rules. Absent when unknown, including results stored before release management. */
|
|
647
|
+
scoringRevision?: number;
|
|
590
648
|
domain: string;
|
|
591
649
|
name: string;
|
|
592
650
|
score: number;
|
|
@@ -712,6 +770,11 @@ export interface components {
|
|
|
712
770
|
recommendation?: string;
|
|
713
771
|
/** @description Why this check does not apply to this product - it is skipped, not a deduction */
|
|
714
772
|
naReason?: string;
|
|
773
|
+
/**
|
|
774
|
+
* @description Present only on 'na' checks that DO apply but could not be checked: 'unverified' means a bot shield answered instead of the site, the server requires authentication, our request got no answer, or a source we query (such as web search) did not reply. Skipped, not deducted, like any 'na'. Absent on an 'na' means the check does not apply to this product.
|
|
775
|
+
* @enum {string}
|
|
776
|
+
*/
|
|
777
|
+
naKind?: "unverified";
|
|
715
778
|
})[];
|
|
716
779
|
})[];
|
|
717
780
|
/** @description Actionable (fail/warning) checks ranked by ora: non-bonus first, then estimated uplift descending, capped at 6. Render verbatim - do not re-rank. */
|
|
@@ -742,7 +805,7 @@ export interface components {
|
|
|
742
805
|
* @description The contract version this payload conforms to. SemVer: a major means a response-envelope break - a stable field removed, renamed, or changed in meaning, or the default response format flipping - and is safe to pin. Additive changes and check-catalog membership changes ship on a minor. See docs/api.md -> Contract and versioning.
|
|
743
806
|
* @enum {string}
|
|
744
807
|
*/
|
|
745
|
-
contractVersion: "1.
|
|
808
|
+
contractVersion: "1.42.0";
|
|
746
809
|
/** @description Wall-clock duration of the scan that produced this stored result */
|
|
747
810
|
durationMs: number | null;
|
|
748
811
|
/**
|
|
@@ -786,11 +849,20 @@ export interface components {
|
|
|
786
849
|
};
|
|
787
850
|
/** @description The complete catalog of scanner checks. Stability classes: every field's shape and presence rule is stable within a major version; layer ids are envelope identity, so removing or renaming one is a major version change; check ids never change meaning while they exist, but catalog membership may change on a minor, with a contract changelog entry and a deprecation window; every other value (scores, weights, layer assignments, applicability, tiers, maturity, prose) is advisory and may change on a minor version, with score-relevant changes recorded in the contract changelog. Gate CI on an explicit list of check ids. */
|
|
788
851
|
CheckCatalog: {
|
|
852
|
+
/** @description Scoring rules version used for this result, independent of contractVersion. Absent when an older result has no recorded version. */
|
|
853
|
+
scoringVersion?: number;
|
|
854
|
+
/**
|
|
855
|
+
* Format: uri
|
|
856
|
+
* @description Machine-readable rules for scoringVersion. Absent when the scoring version is unknown.
|
|
857
|
+
*/
|
|
858
|
+
rulesUrl?: string;
|
|
859
|
+
/** @description Revision of the shared check code under scoringVersion: a result reads as scoringVersion.scoringRevision. A higher revision means a shared check fix that can move scores under the same rules. Absent when unknown, including results stored before release management. */
|
|
860
|
+
scoringRevision?: number;
|
|
789
861
|
/**
|
|
790
862
|
* @description The contract version this catalog conforms to - identical to the OpenAPI info.version and the MCP server version. SemVer: a major means a response-envelope break (a stable field, or a layer id, removed or renamed or changed in meaning, or the default response format flipping) and is safe to pin; check-catalog membership changes ship on a minor. The full versioning policy is published in the API description at /api/openapi.json.
|
|
791
863
|
* @enum {string}
|
|
792
864
|
*/
|
|
793
|
-
contractVersion: "1.
|
|
865
|
+
contractVersion: "1.42.0";
|
|
794
866
|
/** @description The four scored layers in scoring order, with display name and current weight. */
|
|
795
867
|
layers: {
|
|
796
868
|
/** @description Stable layer id: discovery, accessibility, usability, or payments. Removing or renaming a layer id is a major version change. Note one intentional divergence: the id 'accessibility' carries the display name 'Access'. */
|
|
@@ -882,14 +954,27 @@ export interface components {
|
|
|
882
954
|
checkIds: string[];
|
|
883
955
|
/** @description Optional URL of the target's MCP server, matching the same field on POST /api/scan. It pins the MCP endpoint; a failed handshake never substitutes a discovered server. When omitted, ora auto-discovers MCP endpoints. An empty string is treated as absent. */
|
|
884
956
|
mcpUrl?: unknown;
|
|
957
|
+
/** @description Optional. The published scoring version to use for this request. Omitted, the request uses the version pinned to your API key, else the public version. An unpublished or unknown version is refused, and the error lists the published versions. */
|
|
958
|
+
scoringVersion?: number;
|
|
885
959
|
};
|
|
886
960
|
/** @description The outcome of a selective check run. The run always executes - results are never served from a cache. The response carries no aggregate score of any kind: per-check score and maxScore only, with GET /api/score/{domain} as the score surface. Results carry no tier or layer fields - join with GET /api/checks by id to group or rank them. */
|
|
887
961
|
RunChecksResponse: {
|
|
962
|
+
/** @description Scoring rules version used for this result, independent of contractVersion. Absent when an older result has no recorded version. */
|
|
963
|
+
scoringVersion?: number;
|
|
964
|
+
/**
|
|
965
|
+
* Format: uri
|
|
966
|
+
* @description Machine-readable rules for scoringVersion. Absent when the scoring version is unknown.
|
|
967
|
+
*/
|
|
968
|
+
rulesUrl?: string;
|
|
969
|
+
/** @description Revision of the shared check code under scoringVersion: a result reads as scoringVersion.scoringRevision. A higher revision means a shared check fix that can move scores under the same rules. Absent when unknown, including results stored before release management. */
|
|
970
|
+
scoringRevision?: number;
|
|
971
|
+
/** @description Stable managed scan ID. Pass it when polling to keep reading this scan after release assignments change. */
|
|
972
|
+
scanId?: number;
|
|
888
973
|
/**
|
|
889
974
|
* @description The contract version this response conforms to - identical to the OpenAPI info.version and the MCP server version. The full versioning policy is published in the API description at /api/openapi.json.
|
|
890
975
|
* @enum {string}
|
|
891
976
|
*/
|
|
892
|
-
contractVersion: "1.
|
|
977
|
+
contractVersion: "1.42.0";
|
|
893
978
|
/** @description The apex domain derived from the requested URL. */
|
|
894
979
|
domain: string;
|
|
895
980
|
/** @description The normalized URL the run targeted. */
|
|
@@ -924,6 +1009,11 @@ export interface components {
|
|
|
924
1009
|
recommendation?: string;
|
|
925
1010
|
/** @description Why the check did not apply. Present on 'na' results, including requested ids that cannot apply to the detected kind. */
|
|
926
1011
|
naReason?: string;
|
|
1012
|
+
/**
|
|
1013
|
+
* @description Present only on 'na' results that DO apply but could not be checked: 'unverified' means a bot shield answered instead of the site, the server requires authentication, ora's request got no answer, or a source ora queries (such as web search) did not reply. Absent on an 'na' result means the check does not apply.
|
|
1014
|
+
* @enum {string}
|
|
1015
|
+
*/
|
|
1016
|
+
naKind?: "unverified";
|
|
927
1017
|
/**
|
|
928
1018
|
* @description The classification of the MCP surface this entry scored against - one of: product | docs | other | app. Present on MCP fan-out entries.
|
|
929
1019
|
* @enum {string}
|
|
@@ -962,6 +1052,23 @@ export interface components {
|
|
|
962
1052
|
verdict?: "satisfied" | "partial" | "unsatisfied" | "not_gradable";
|
|
963
1053
|
/** @description Billable steps the run took (tool calls, excluding narration and filesystem ops), present once the run finished. This is the same counter run pricing uses. */
|
|
964
1054
|
step_count?: number;
|
|
1055
|
+
/** @description Two notes that sit beside the verdict and never change it, present with the verdict once the run finished. */
|
|
1056
|
+
flags?: {
|
|
1057
|
+
/** @description The site refused the agent: its first request to the site that got an HTTP status was a 403 or 429, or more than half of those requests were a 401, 403 or 429. A 401 alone on the first request does not count, and a 404 never counts. */
|
|
1058
|
+
blocked: {
|
|
1059
|
+
/** @description Whether the note applies to this run */
|
|
1060
|
+
flagged: boolean;
|
|
1061
|
+
/** @description The note in plain words, present only when flagged */
|
|
1062
|
+
reason?: string;
|
|
1063
|
+
};
|
|
1064
|
+
/** @description Half or more of the answer came from the model's memory rather than from pages it fetched. */
|
|
1065
|
+
answered_from_memory: {
|
|
1066
|
+
/** @description Whether the note applies to this run */
|
|
1067
|
+
flagged: boolean;
|
|
1068
|
+
/** @description The note in plain words, present only when flagged */
|
|
1069
|
+
reason?: string;
|
|
1070
|
+
};
|
|
1071
|
+
};
|
|
965
1072
|
/** @description Journey/audit contract version (shared SemVer; see docs) */
|
|
966
1073
|
contractVersion: string;
|
|
967
1074
|
};
|
|
@@ -995,10 +1102,45 @@ export interface components {
|
|
|
995
1102
|
verdict?: "satisfied" | "partial" | "unsatisfied" | "not_gradable";
|
|
996
1103
|
/** @description Billable steps the run took (tool calls, excluding narration and filesystem ops), present once the run finished. This is the same counter run pricing uses. */
|
|
997
1104
|
step_count?: number;
|
|
1105
|
+
/** @description Two notes that sit beside the verdict and never change it, present with the verdict once the run finished. */
|
|
1106
|
+
flags?: {
|
|
1107
|
+
/** @description The site refused the agent: its first request to the site that got an HTTP status was a 403 or 429, or more than half of those requests were a 401, 403 or 429. A 401 alone on the first request does not count, and a 404 never counts. */
|
|
1108
|
+
blocked: {
|
|
1109
|
+
/** @description Whether the note applies to this run */
|
|
1110
|
+
flagged: boolean;
|
|
1111
|
+
/** @description The note in plain words, present only when flagged */
|
|
1112
|
+
reason?: string;
|
|
1113
|
+
};
|
|
1114
|
+
/** @description Half or more of the answer came from the model's memory rather than from pages it fetched. */
|
|
1115
|
+
answered_from_memory: {
|
|
1116
|
+
/** @description Whether the note applies to this run */
|
|
1117
|
+
flagged: boolean;
|
|
1118
|
+
/** @description The note in plain words, present only when flagged */
|
|
1119
|
+
reason?: string;
|
|
1120
|
+
};
|
|
1121
|
+
};
|
|
998
1122
|
/** @description Journey/audit contract version (shared SemVer; see docs) */
|
|
999
1123
|
contractVersion: string;
|
|
1000
1124
|
/** @description Echo of the custom intent text the caller sent on this request. Create-response-only: it is never returned by GET /api/journey/runs/{id} or the capped 200, and it is absent on curated runs. Experimental: may change or disappear without a major version. */
|
|
1001
1125
|
intent?: string;
|
|
1126
|
+
/** @description The one request to send next: the run's stream, held open to the end, because only a followed stream saves the result */
|
|
1127
|
+
next_action?: {
|
|
1128
|
+
/**
|
|
1129
|
+
* @description HTTP method of the next request
|
|
1130
|
+
* @enum {string}
|
|
1131
|
+
*/
|
|
1132
|
+
method: "GET" | "POST";
|
|
1133
|
+
/** @description Where to send it: an API path on this origin, or an absolute URL for a docs page */
|
|
1134
|
+
url: string;
|
|
1135
|
+
/** @description JSON body to send with it, when it takes one: the caller's own request, replayed */
|
|
1136
|
+
body?: {
|
|
1137
|
+
[key: string]: unknown;
|
|
1138
|
+
};
|
|
1139
|
+
/** @description Seconds to wait before sending it */
|
|
1140
|
+
wait_seconds?: number;
|
|
1141
|
+
/** @description Why this request is the recommended next step */
|
|
1142
|
+
reason: string;
|
|
1143
|
+
};
|
|
1002
1144
|
};
|
|
1003
1145
|
JourneyCappedRun: {
|
|
1004
1146
|
/** @description Run id - the handle for GET /api/journey/runs/{id} and the stream */
|
|
@@ -1030,6 +1172,23 @@ export interface components {
|
|
|
1030
1172
|
verdict?: "satisfied" | "partial" | "unsatisfied" | "not_gradable";
|
|
1031
1173
|
/** @description Billable steps the run took (tool calls, excluding narration and filesystem ops), present once the run finished. This is the same counter run pricing uses. */
|
|
1032
1174
|
step_count?: number;
|
|
1175
|
+
/** @description Two notes that sit beside the verdict and never change it, present with the verdict once the run finished. */
|
|
1176
|
+
flags?: {
|
|
1177
|
+
/** @description The site refused the agent: its first request to the site that got an HTTP status was a 403 or 429, or more than half of those requests were a 401, 403 or 429. A 401 alone on the first request does not count, and a 404 never counts. */
|
|
1178
|
+
blocked: {
|
|
1179
|
+
/** @description Whether the note applies to this run */
|
|
1180
|
+
flagged: boolean;
|
|
1181
|
+
/** @description The note in plain words, present only when flagged */
|
|
1182
|
+
reason?: string;
|
|
1183
|
+
};
|
|
1184
|
+
/** @description Half or more of the answer came from the model's memory rather than from pages it fetched. */
|
|
1185
|
+
answered_from_memory: {
|
|
1186
|
+
/** @description Whether the note applies to this run */
|
|
1187
|
+
flagged: boolean;
|
|
1188
|
+
/** @description The note in plain words, present only when flagged */
|
|
1189
|
+
reason?: string;
|
|
1190
|
+
};
|
|
1191
|
+
};
|
|
1033
1192
|
/** @description Journey/audit contract version (shared SemVer; see docs) */
|
|
1034
1193
|
contractVersion: string;
|
|
1035
1194
|
/**
|
|
@@ -1046,6 +1205,24 @@ export interface components {
|
|
|
1046
1205
|
};
|
|
1047
1206
|
/** @description Milliseconds until a per-target slot frees */
|
|
1048
1207
|
retry_after_ms: number;
|
|
1208
|
+
/** @description The one request to send next for the served run: its stream while it is running or for 15 minutes after it failed, or the run itself for its full result once it succeeded */
|
|
1209
|
+
next_action?: {
|
|
1210
|
+
/**
|
|
1211
|
+
* @description HTTP method of the next request
|
|
1212
|
+
* @enum {string}
|
|
1213
|
+
*/
|
|
1214
|
+
method: "GET" | "POST";
|
|
1215
|
+
/** @description Where to send it: an API path on this origin, or an absolute URL for a docs page */
|
|
1216
|
+
url: string;
|
|
1217
|
+
/** @description JSON body to send with it, when it takes one: the caller's own request, replayed */
|
|
1218
|
+
body?: {
|
|
1219
|
+
[key: string]: unknown;
|
|
1220
|
+
};
|
|
1221
|
+
/** @description Seconds to wait before sending it */
|
|
1222
|
+
wait_seconds?: number;
|
|
1223
|
+
/** @description Why this request is the recommended next step */
|
|
1224
|
+
reason: string;
|
|
1225
|
+
};
|
|
1049
1226
|
};
|
|
1050
1227
|
JourneyRunDetail: {
|
|
1051
1228
|
/** @description Run id - the handle for GET /api/journey/runs/{id} and the stream */
|
|
@@ -1077,6 +1254,23 @@ export interface components {
|
|
|
1077
1254
|
verdict?: "satisfied" | "partial" | "unsatisfied" | "not_gradable";
|
|
1078
1255
|
/** @description Billable steps the run took (tool calls, excluding narration and filesystem ops), present once the run finished. This is the same counter run pricing uses. */
|
|
1079
1256
|
step_count?: number;
|
|
1257
|
+
/** @description Two notes that sit beside the verdict and never change it, present with the verdict once the run finished. */
|
|
1258
|
+
flags?: {
|
|
1259
|
+
/** @description The site refused the agent: its first request to the site that got an HTTP status was a 403 or 429, or more than half of those requests were a 401, 403 or 429. A 401 alone on the first request does not count, and a 404 never counts. */
|
|
1260
|
+
blocked: {
|
|
1261
|
+
/** @description Whether the note applies to this run */
|
|
1262
|
+
flagged: boolean;
|
|
1263
|
+
/** @description The note in plain words, present only when flagged */
|
|
1264
|
+
reason?: string;
|
|
1265
|
+
};
|
|
1266
|
+
/** @description Half or more of the answer came from the model's memory rather than from pages it fetched. */
|
|
1267
|
+
answered_from_memory: {
|
|
1268
|
+
/** @description Whether the note applies to this run */
|
|
1269
|
+
flagged: boolean;
|
|
1270
|
+
/** @description The note in plain words, present only when flagged */
|
|
1271
|
+
reason?: string;
|
|
1272
|
+
};
|
|
1273
|
+
};
|
|
1080
1274
|
/** @description Journey/audit contract version (shared SemVer; see docs) */
|
|
1081
1275
|
contractVersion: string;
|
|
1082
1276
|
/** @description The full run result. Present iff status is 'succeeded'. */
|
|
@@ -1333,6 +1527,41 @@ export interface components {
|
|
|
1333
1527
|
journey_layers?: ("discovery" | "identity" | "access" | "payments" | "experience")[];
|
|
1334
1528
|
};
|
|
1335
1529
|
};
|
|
1530
|
+
/** @description The one request to send next: the run's stream while it is running, or for 15 minutes after it failed, since reopening it reconnects a run that only lost its connection. Absent once the run succeeded, because the result is in this body, and once a failure is older than 15 minutes, because the run is final. */
|
|
1531
|
+
next_action?: {
|
|
1532
|
+
/**
|
|
1533
|
+
* @description HTTP method of the next request
|
|
1534
|
+
* @enum {string}
|
|
1535
|
+
*/
|
|
1536
|
+
method: "GET" | "POST";
|
|
1537
|
+
/** @description Where to send it: an API path on this origin, or an absolute URL for a docs page */
|
|
1538
|
+
url: string;
|
|
1539
|
+
/** @description JSON body to send with it, when it takes one: the caller's own request, replayed */
|
|
1540
|
+
body?: {
|
|
1541
|
+
[key: string]: unknown;
|
|
1542
|
+
};
|
|
1543
|
+
/** @description Seconds to wait before sending it */
|
|
1544
|
+
wait_seconds?: number;
|
|
1545
|
+
/** @description Why this request is the recommended next step */
|
|
1546
|
+
reason: string;
|
|
1547
|
+
};
|
|
1548
|
+
};
|
|
1549
|
+
JourneyNextAction: {
|
|
1550
|
+
/**
|
|
1551
|
+
* @description HTTP method of the next request
|
|
1552
|
+
* @enum {string}
|
|
1553
|
+
*/
|
|
1554
|
+
method: "GET" | "POST";
|
|
1555
|
+
/** @description Where to send it: an API path on this origin, or an absolute URL for a docs page */
|
|
1556
|
+
url: string;
|
|
1557
|
+
/** @description JSON body to send with it, when it takes one: the caller's own request, replayed */
|
|
1558
|
+
body?: {
|
|
1559
|
+
[key: string]: unknown;
|
|
1560
|
+
};
|
|
1561
|
+
/** @description Seconds to wait before sending it */
|
|
1562
|
+
wait_seconds?: number;
|
|
1563
|
+
/** @description Why this request is the recommended next step */
|
|
1564
|
+
reason: string;
|
|
1336
1565
|
};
|
|
1337
1566
|
JourneyDomainRun: {
|
|
1338
1567
|
/** @description Run id - the handle for GET /api/journey/runs/{id} and the stream */
|
|
@@ -1364,6 +1593,23 @@ export interface components {
|
|
|
1364
1593
|
verdict?: "satisfied" | "partial" | "unsatisfied" | "not_gradable";
|
|
1365
1594
|
/** @description Billable steps the run took (tool calls, excluding narration and filesystem ops), present once the run finished. This is the same counter run pricing uses. */
|
|
1366
1595
|
step_count?: number;
|
|
1596
|
+
/** @description Two notes that sit beside the verdict and never change it, present with the verdict once the run finished. */
|
|
1597
|
+
flags?: {
|
|
1598
|
+
/** @description The site refused the agent: its first request to the site that got an HTTP status was a 403 or 429, or more than half of those requests were a 401, 403 or 429. A 401 alone on the first request does not count, and a 404 never counts. */
|
|
1599
|
+
blocked: {
|
|
1600
|
+
/** @description Whether the note applies to this run */
|
|
1601
|
+
flagged: boolean;
|
|
1602
|
+
/** @description The note in plain words, present only when flagged */
|
|
1603
|
+
reason?: string;
|
|
1604
|
+
};
|
|
1605
|
+
/** @description Half or more of the answer came from the model's memory rather than from pages it fetched. */
|
|
1606
|
+
answered_from_memory: {
|
|
1607
|
+
/** @description Whether the note applies to this run */
|
|
1608
|
+
flagged: boolean;
|
|
1609
|
+
/** @description The note in plain words, present only when flagged */
|
|
1610
|
+
reason?: string;
|
|
1611
|
+
};
|
|
1612
|
+
};
|
|
1367
1613
|
/** @description Journey/audit contract version (shared SemVer; see docs) */
|
|
1368
1614
|
contractVersion: string;
|
|
1369
1615
|
/** @description The full run result. Present iff status is 'succeeded'. */
|
|
@@ -1657,6 +1903,23 @@ export interface components {
|
|
|
1657
1903
|
verdict?: "satisfied" | "partial" | "unsatisfied" | "not_gradable";
|
|
1658
1904
|
/** @description Billable steps the run took (tool calls, excluding narration and filesystem ops), present once the run finished. This is the same counter run pricing uses. */
|
|
1659
1905
|
step_count?: number;
|
|
1906
|
+
/** @description Two notes that sit beside the verdict and never change it, present with the verdict once the run finished. */
|
|
1907
|
+
flags?: {
|
|
1908
|
+
/** @description The site refused the agent: its first request to the site that got an HTTP status was a 403 or 429, or more than half of those requests were a 401, 403 or 429. A 401 alone on the first request does not count, and a 404 never counts. */
|
|
1909
|
+
blocked: {
|
|
1910
|
+
/** @description Whether the note applies to this run */
|
|
1911
|
+
flagged: boolean;
|
|
1912
|
+
/** @description The note in plain words, present only when flagged */
|
|
1913
|
+
reason?: string;
|
|
1914
|
+
};
|
|
1915
|
+
/** @description Half or more of the answer came from the model's memory rather than from pages it fetched. */
|
|
1916
|
+
answered_from_memory: {
|
|
1917
|
+
/** @description Whether the note applies to this run */
|
|
1918
|
+
flagged: boolean;
|
|
1919
|
+
/** @description The note in plain words, present only when flagged */
|
|
1920
|
+
reason?: string;
|
|
1921
|
+
};
|
|
1922
|
+
};
|
|
1660
1923
|
/** @description Journey/audit contract version (shared SemVer; see docs) */
|
|
1661
1924
|
contractVersion: string;
|
|
1662
1925
|
/** @description The graph-view run result. Present iff status is 'succeeded'. */
|
|
@@ -2059,8 +2322,96 @@ export interface components {
|
|
|
2059
2322
|
/** @description text steps only: the narrative the agent emitted between actions. Advisory - raw model prose. */
|
|
2060
2323
|
text?: string;
|
|
2061
2324
|
};
|
|
2325
|
+
ScoringRules: {
|
|
2326
|
+
scoringVersion: number;
|
|
2327
|
+
/** Format: uri */
|
|
2328
|
+
rulesUrl: string;
|
|
2329
|
+
/** @description The current revision of the shared check code. Results scored now read as scoringVersion.scoringRevision. */
|
|
2330
|
+
scoringRevision?: number;
|
|
2331
|
+
/** @description Content hash of the scoring rules. */
|
|
2332
|
+
rulesHash: string;
|
|
2333
|
+
/** @description Publication timestamp, or null for an available legacy version before managed publication. */
|
|
2334
|
+
publishedAt: string | null;
|
|
2335
|
+
rules: components["schemas"]["ScoringManifest"];
|
|
2336
|
+
};
|
|
2337
|
+
ScoringManifest: {
|
|
2338
|
+
version: number;
|
|
2339
|
+
/** @description Identity of the check evaluation rules. */
|
|
2340
|
+
evaluationRules: string;
|
|
2341
|
+
/** @description Scored checks only. Use the assigned check catalog for unscored checks and fix guidance. */
|
|
2342
|
+
checks: {
|
|
2343
|
+
id: string;
|
|
2344
|
+
layer: string;
|
|
2345
|
+
maxScore: number;
|
|
2346
|
+
bonus: boolean;
|
|
2347
|
+
}[];
|
|
2348
|
+
layers: {
|
|
2349
|
+
id: string;
|
|
2350
|
+
weight: number;
|
|
2351
|
+
}[];
|
|
2352
|
+
formula: {
|
|
2353
|
+
aggregation: string;
|
|
2354
|
+
notApplicable: string;
|
|
2355
|
+
emerging: string;
|
|
2356
|
+
bonus: string;
|
|
2357
|
+
emptyLayerWeight: string;
|
|
2358
|
+
normalization: string;
|
|
2359
|
+
emptyScore: number;
|
|
2360
|
+
rounding: string;
|
|
2361
|
+
checkRescaling: string;
|
|
2362
|
+
};
|
|
2363
|
+
rules: {
|
|
2364
|
+
scoreGate: {
|
|
2365
|
+
checkIds: string[];
|
|
2366
|
+
cap: number;
|
|
2367
|
+
} | null;
|
|
2368
|
+
useLayerMinMaxScore: number;
|
|
2369
|
+
};
|
|
2370
|
+
/** @description Scoring behavior switches enabled for this version. */
|
|
2371
|
+
switches: {
|
|
2372
|
+
paymentScoring?: string;
|
|
2373
|
+
[key: string]: (boolean | string) | undefined;
|
|
2374
|
+
};
|
|
2375
|
+
};
|
|
2376
|
+
DeepCheckResponse: {
|
|
2377
|
+
scanId?: number;
|
|
2378
|
+
scoringVersion?: number;
|
|
2379
|
+
/** Format: uri */
|
|
2380
|
+
rulesUrl?: string;
|
|
2381
|
+
/** @description Revision of the shared check code the scan ran with. Absent when unknown. */
|
|
2382
|
+
scoringRevision?: number;
|
|
2383
|
+
allComplete: boolean;
|
|
2384
|
+
allReady: boolean;
|
|
2385
|
+
agenticSummary?: string;
|
|
2386
|
+
checks: {
|
|
2387
|
+
checkId: string;
|
|
2388
|
+
status: string;
|
|
2389
|
+
score: number;
|
|
2390
|
+
maxScore: number;
|
|
2391
|
+
details: string;
|
|
2392
|
+
recommendation?: string;
|
|
2393
|
+
naReason?: string;
|
|
2394
|
+
mcpKind?: string;
|
|
2395
|
+
mcpUrl?: string;
|
|
2396
|
+
progress?: Record<string, never>[];
|
|
2397
|
+
data?: {
|
|
2398
|
+
[key: string]: unknown;
|
|
2399
|
+
};
|
|
2400
|
+
}[];
|
|
2401
|
+
};
|
|
2062
2402
|
/** @description The default response body of POST /api/scan and GET /api/score/{domain}. Fields not listed below may be present: they are ora internals, are not part of the contract, and may change or disappear in any release without a major version bump. Pass `?format=audit` for the versioned, fully documented shape (AuditScanResult / AuditScoreResult). */
|
|
2063
2403
|
ScanResult: {
|
|
2404
|
+
/** @description Stable managed scan ID. Preserve it when polling this result. */
|
|
2405
|
+
scanId?: number;
|
|
2406
|
+
/** @description The checks and scoring rules used for this result. Absent when the stored version is unknown. */
|
|
2407
|
+
scoringVersion?: number;
|
|
2408
|
+
/**
|
|
2409
|
+
* Format: uri
|
|
2410
|
+
* @description The machine-readable rules for scoringVersion. Absent when the stored version is unknown.
|
|
2411
|
+
*/
|
|
2412
|
+
rulesUrl?: string;
|
|
2413
|
+
/** @description Revision of the shared check code under scoringVersion: the result reads as scoringVersion.scoringRevision. A higher revision means a shared check fix that can move scores under the same rules. Absent when unknown, including results stored before release management. */
|
|
2414
|
+
scoringRevision?: number;
|
|
2064
2415
|
/** @description The scanned domain (pre-redirect). Compare with new URL(finalUrl).hostname to detect cross-domain redirects. */
|
|
2065
2416
|
domain?: string;
|
|
2066
2417
|
/** @description The normalized URL */
|
|
@@ -2164,6 +2515,11 @@ export interface components {
|
|
|
2164
2515
|
tier?: "required" | "recommended" | "emerging";
|
|
2165
2516
|
/** @description Optional. Why the check does not apply to this product. Present on 'na' rows; the check is skipped, not deducted. */
|
|
2166
2517
|
naReason?: string;
|
|
2518
|
+
/**
|
|
2519
|
+
* @description Optional. Present only on 'na' rows that DO apply but could not be checked: 'unverified' means a bot shield answered instead of the site, the server requires authentication, ora's request got no answer, or a source ora queries (such as web search) did not reply. Skipped, not deducted, like any 'na'. Absent on an 'na' row means the check does not apply to this product.
|
|
2520
|
+
* @enum {string}
|
|
2521
|
+
*/
|
|
2522
|
+
naKind?: "unverified";
|
|
2167
2523
|
/** @description Optional. Estimated points fully fixing this check would add to the overall 0-100 score, already normalized to the layer weight. Present on actionable (fail/warning) checks only; an estimate, not exact. This is the uplift signal - do not read maxScore minus score as score uplift. */
|
|
2168
2524
|
estScoreGain?: number;
|
|
2169
2525
|
};
|
|
@@ -2284,6 +2640,77 @@ export interface components {
|
|
|
2284
2640
|
/** @description Optional recovery hint (e.g. /api/scan on NOT_FOUND). */
|
|
2285
2641
|
next?: string;
|
|
2286
2642
|
};
|
|
2643
|
+
/**
|
|
2644
|
+
* @description A partner key's usage per kind, returned by GET /api/usage. Each kind holds one entry per period: day (calendar day, UTC) and month (calendar month, UTC). A future period is a sibling key next to them.
|
|
2645
|
+
* @example {
|
|
2646
|
+
* "key": "acme",
|
|
2647
|
+
* "scans": {
|
|
2648
|
+
* "day": {
|
|
2649
|
+
* "used": 40,
|
|
2650
|
+
* "limit": 200,
|
|
2651
|
+
* "remaining": 160,
|
|
2652
|
+
* "period_start": "2026-10-14T00:00:00.000Z",
|
|
2653
|
+
* "resets_at": "2026-10-15T00:00:00.000Z"
|
|
2654
|
+
* },
|
|
2655
|
+
* "month": {
|
|
2656
|
+
* "used": 1250,
|
|
2657
|
+
* "limit": 5000,
|
|
2658
|
+
* "remaining": 3750,
|
|
2659
|
+
* "period_start": "2026-10-01T00:00:00.000Z",
|
|
2660
|
+
* "resets_at": "2026-11-01T00:00:00.000Z"
|
|
2661
|
+
* }
|
|
2662
|
+
* },
|
|
2663
|
+
* "journeys": {
|
|
2664
|
+
* "day": {
|
|
2665
|
+
* "used": 1,
|
|
2666
|
+
* "limit": null,
|
|
2667
|
+
* "remaining": null,
|
|
2668
|
+
* "period_start": "2026-10-14T00:00:00.000Z",
|
|
2669
|
+
* "resets_at": "2026-10-15T00:00:00.000Z"
|
|
2670
|
+
* },
|
|
2671
|
+
* "month": {
|
|
2672
|
+
* "used": 12,
|
|
2673
|
+
* "limit": null,
|
|
2674
|
+
* "remaining": null,
|
|
2675
|
+
* "period_start": "2026-10-01T00:00:00.000Z",
|
|
2676
|
+
* "resets_at": "2026-11-01T00:00:00.000Z"
|
|
2677
|
+
* }
|
|
2678
|
+
* }
|
|
2679
|
+
* }
|
|
2680
|
+
*/
|
|
2681
|
+
KeyUsage: {
|
|
2682
|
+
/** @description The name of the key that made the request. */
|
|
2683
|
+
key: string;
|
|
2684
|
+
/** @description Scan dispatches: POST /api/scan, GET /api/scan/stream, POST /api/scan/checks, POST /api/v2/scan and the MCP scan_domain and run_checks tools. */
|
|
2685
|
+
scans: {
|
|
2686
|
+
day: components["schemas"]["KeyUsagePeriod"];
|
|
2687
|
+
month: components["schemas"]["KeyUsagePeriod"];
|
|
2688
|
+
};
|
|
2689
|
+
/** @description Journey dispatches: POST /api/journey/runs and POST /api/journey/domains/{host}. */
|
|
2690
|
+
journeys: {
|
|
2691
|
+
day: components["schemas"]["KeyUsagePeriod"];
|
|
2692
|
+
month: components["schemas"]["KeyUsagePeriod"];
|
|
2693
|
+
};
|
|
2694
|
+
};
|
|
2695
|
+
/** @description One kind's usage in one period. */
|
|
2696
|
+
KeyUsagePeriod: {
|
|
2697
|
+
/** @description New dispatches the key started since period_start. */
|
|
2698
|
+
used: number;
|
|
2699
|
+
/** @description The key's limit for this kind and period; null when it has none. */
|
|
2700
|
+
limit: number | null;
|
|
2701
|
+
/** @description limit minus used, never below 0; null when there is no limit. At 0 the endpoints that dispatch this kind answer 429 usage_limit_reached until resets_at. */
|
|
2702
|
+
remaining: number | null;
|
|
2703
|
+
/**
|
|
2704
|
+
* Format: date-time
|
|
2705
|
+
* @description Start of the current period: 00:00 UTC today for day, the 1st of the month at 00:00 UTC for month.
|
|
2706
|
+
*/
|
|
2707
|
+
period_start: string;
|
|
2708
|
+
/**
|
|
2709
|
+
* Format: date-time
|
|
2710
|
+
* @description When the count resets: 00:00 UTC tomorrow for day, the 1st of next month at 00:00 UTC for month.
|
|
2711
|
+
*/
|
|
2712
|
+
resets_at: string;
|
|
2713
|
+
};
|
|
2287
2714
|
/** @description Draft agent discovery files for one domain, returned by GET /api/agent-files/{domain}. */
|
|
2288
2715
|
AgentFilesBundle: {
|
|
2289
2716
|
/** @description The domain the files speak for (leading www. dropped). */
|
|
@@ -2585,6 +3012,8 @@ export interface operations {
|
|
|
2585
3012
|
siteType?: "content" | "business" | "app" | "store";
|
|
2586
3013
|
/** @description Optional, defaults to false. A few checks confirm that an endpoint the site declares for agents enforces what it declares by sending it a request that must be refused (for example an unauthenticated POST). Pass true to send those requests for this scan; without it the affected checks reuse the domain's previous result where one exists. */
|
|
2587
3014
|
activeProbes?: boolean;
|
|
3015
|
+
/** @description Optional. The published scoring version to use for this request. Omitted, the request uses the version pinned to your API key, else the public version. An unpublished or unknown version answers 400 `scoring_version_unavailable` listing the published versions; a value that is not a positive integer answers 400 `invalid_scoring_version`. Until release management is active, a request can name 3 (the same opt-in as the older `rankerVersion: 3`) or the version it would run anyway; any other version answers 400. A version other than the one a domain was last scanned under has no stored result yet, so the first scan of a domain under it runs live. */
|
|
3016
|
+
scoringVersion?: number;
|
|
2588
3017
|
};
|
|
2589
3018
|
};
|
|
2590
3019
|
};
|
|
@@ -2607,7 +3036,7 @@ export interface operations {
|
|
|
2607
3036
|
/** @description Scan accepted and scored, but analysis is still in progress (analysisStatus is 'partial'). The body is the same shape as a 200 (including `competitors` when `?competitors=1` was passed, and `#/components/schemas/AuditScanResult` when `?format=audit` was passed). Poll the Location header URL (GET /api/score/{domain}) until analysisStatus is 'complete' and pendingChecks is empty. */
|
|
2608
3037
|
202: {
|
|
2609
3038
|
headers: {
|
|
2610
|
-
/** @description URL of the scan result resource to poll
|
|
3039
|
+
/** @description URL of the scan result resource to poll. Managed scans include scanId; preserve the complete Location URL. */
|
|
2611
3040
|
Location?: string;
|
|
2612
3041
|
};
|
|
2613
3042
|
content: {
|
|
@@ -2629,7 +3058,7 @@ export interface operations {
|
|
|
2629
3058
|
"application/json": components["schemas"]["McpAuthRequiredResponse"];
|
|
2630
3059
|
};
|
|
2631
3060
|
};
|
|
2632
|
-
/** @description Rate limit exceeded - either the 10-per-minute burst cap or the durable daily quota (30 scans per rolling 24h per IP; 6 per day for force=true). Cache-served responses never count against the daily quota. The response includes a Retry-After header indicating seconds until the next request is allowed, and a JSON body with error and retry_after_ms. */
|
|
3061
|
+
/** @description Rate limit exceeded - either the 10-per-minute burst cap or the durable daily quota (30 scans per rolling 24h per IP; 6 per day for force=true). Cache-served responses never count against the daily quota. The response includes a Retry-After header indicating seconds until the next request is allowed, and a JSON body with error and retry_after_ms. A keyed caller whose key has used its daily or monthly scan limit gets 429 with error `usage_limit_reached` and `kind`, `period` (`day` or `month`), `used`, `limit`, `resets_at` and `retry_after_ms`; its Retry-After counts to `resets_at`: the next 00:00 UTC for a daily limit, the next 1st of the month (UTC) for a monthly one, and the later of the two when both are used up. That refusal is key-wide; GET /api/usage shows the numbers. */
|
|
2633
3062
|
429: {
|
|
2634
3063
|
headers: {
|
|
2635
3064
|
/** @description Seconds until next allowed request */
|
|
@@ -2707,7 +3136,7 @@ export interface operations {
|
|
|
2707
3136
|
"application/json": components["schemas"]["ErrorResponse"];
|
|
2708
3137
|
};
|
|
2709
3138
|
};
|
|
2710
|
-
/** @description Rate limit exceeded - either the 10-per-minute burst cap or the durable daily quota (30 scans per rolling 24h per IP), which this endpoint spends from the same budget as the v1 scan routes so a caller cannot drain it twice by switching endpoints. The response carries a Retry-After header; a durable deny also carries retry_after_ms in the body. */
|
|
3139
|
+
/** @description Rate limit exceeded - either the 10-per-minute burst cap or the durable daily quota (30 scans per rolling 24h per IP), which this endpoint spends from the same budget as the v1 scan routes so a caller cannot drain it twice by switching endpoints. The response carries a Retry-After header; a durable deny also carries retry_after_ms in the body. A keyed caller whose key has used its daily or monthly scan limit gets 429 with error `usage_limit_reached` and `kind`, `period` (`day` or `month`), `used`, `limit`, `resets_at` and `retry_after_ms`; its Retry-After counts to `resets_at`: the next 00:00 UTC for a daily limit, the next 1st of the month (UTC) for a monthly one, and the later of the two when both are used up. That refusal is key-wide; GET /api/usage shows the numbers. */
|
|
2711
3140
|
429: {
|
|
2712
3141
|
headers: {
|
|
2713
3142
|
/** @description Seconds until next allowed request */
|
|
@@ -2748,6 +3177,8 @@ export interface operations {
|
|
|
2748
3177
|
ephemeral?: "1";
|
|
2749
3178
|
/** @description Pass 1 to send the requests a few checks send to endpoints the site declares for agents - the query spelling of `activeProbes: true` on POST /api/scan. Absent, they are not sent. */
|
|
2750
3179
|
activeProbes?: "1";
|
|
3180
|
+
/** @description Optional. The published scoring version to use for this request. Omitted, the request uses the version pinned to your API key, else the public version. An unpublished or unknown version answers 400 `scoring_version_unavailable` listing the published versions; a value that is not a positive integer answers 400 `invalid_scoring_version`. Until release management is active, a request can name 3 (the same opt-in as the older `rankerVersion: 3`) or the version it would run anyway; any other version answers 400. A version other than the one a domain was last scanned under has no stored result yet, so the first scan of a domain under it runs live. */
|
|
3181
|
+
scoringVersion?: number;
|
|
2751
3182
|
/** @description Pass `audit` to receive the versioned, allowlisted audit shape (AuditScanResult / AuditScoreResult) instead of the default body: every field is documented, carries a `contractVersion`, and internal fields are dropped. Omit it and the response is unchanged from previous releases. On GET /api/scan/stream, only the `scan_complete` event's `result` is projected - all other events are identical to the default stream. */
|
|
2752
3183
|
format?: "audit";
|
|
2753
3184
|
/** @description Opt-in expansion list (comma-separated). Experimental: the audit schemas declare `siteType` only as a loose object, so its inner fields may change without a version bump, and pinning the contract major does not freeze them. `siteType` adds one response key, `siteType`: the same scan scored against what the site is (`content`, `business`, `app`, or `store`). It carries `type`, `source` (`declared`, `self-declared`, `classified`, `default`, `blocked`, or `unavailable`), `confidence` (`high` or `low`), `basis`, `score` (0-100 or null), per-layer `layers` (`id`, `score`, `maxScore`), per-check `states` (`req`, `bonus`, `gated`, or `emerging`), and `gatedOut` (each excluded check id with the gate that excluded it). A site-type score uses a different rubric from the canonical `score` and can land above or below it: never compare the two, only another `siteType.score` of the same `type`. When no type resolves, the key is `{ type: null, source: "unavailable", confidence: "low", score: null, layers: [] }` with a `basis` saying why. On the stream the key rides the `scan_complete` event beside `result`, never inside it. */
|
|
@@ -2757,7 +3188,7 @@ export interface operations {
|
|
|
2757
3188
|
};
|
|
2758
3189
|
};
|
|
2759
3190
|
responses: {
|
|
2760
|
-
/** @description Server-Sent Events stream of scan progress. If MCP authentication is required, the stream ends with an error event carrying code MCP_AUTH_REQUIRED, mcpAuthRequired: true, mcpUrl and urlKind, without scan_complete or a score. With `?format=audit`, the `scan_complete` event's `result` is `#/components/schemas/AuditScanResult`; every other event is unchanged. When a stored result inside the freshness window answers the request, the stream is a `kind_detected` frame followed by a terminal `scan_complete` event carrying `servedFromCache: true` and `resultAgeSeconds`, and the response carries an `Age` header. After `scan_complete`, a live scan may emit two correction events before the stream closes, both optional: `relevance_assessed` (`{ naCheckIds, reasons, score, grade }`, only when some checks are judged not applicable for this product) carries the corrected `score` and `grade`, and `summary_ready` (`{ agenticSummary }`) carries the summary. Consume events until the stream closes. Closing does not mean the analysis is final: when deep checks are still pending, the stream closes early and a background worker finishes relevance and summary later. Read GET /api/score/{domain} after the stream closes and poll it while `analysisStatus` is `partial`. A freshness-window hit is already final and emits neither event. Event types (the `type` field), in emission order: `kind_detecting` - reachability passed and URL-kind detection is running (no payload); `kind_detected` - detection resolved: `{ kind: 'domain' | 'mcp' | 'mcp-app', mcpUrl?, embeddedMcpUrls?, hint? }`, exactly once, before any `check_start`; `discovery_phase` (optional) - a context-gathering step, or after `scan_complete` a post-scan finalize step: `{ step, label?, stepIndex?, totalSteps? }`, zero or more times; `scan_init` - the check plan: `{ layerMaxScores, totalChecks?, checkRoster?, staticOnly? }`; may be sent twice, the later one is authoritative; `check_start` - one check slot started: `{ layerId, layerName, checkId, checkName, mcpKind?, mcpUrl? }`; `check_complete` - one check slot finished: `{ layerId, layerName, checkId, checkName, status, score, maxScore, details?, bonus?, maturity?, mcpKind?, mcpUrl? }`; `layer_complete` - every check in a layer finished: `{ layerId, layerName }`; `scan_complete` - the scored result, not the last frame: `{ result }` (AuditScanResult under `?format=audit`), plus `siteType` with `?include=siteType` and `servedFromCache` / `resultAgeSeconds` on a freshness hit; `relevance_assessed` (optional) - after `scan_complete`, only when checks were judged not applicable: `{ naCheckIds, reasons, score, grade }` with the corrected score and grade; `summary_ready` (optional) - after `scan_complete`: `{ agenticSummary }`; `error` (terminal, optional) - the scan failed and no `scan_complete` follows: `{ message }`, plus `code: 'MCP_AUTH_REQUIRED'`, `mcpAuthRequired`, `mcpUrl` and `urlKind` when an MCP server requires authentication. Read until the stream closes; only a terminal event is guaranteed to be the last frame. */
|
|
3191
|
+
/** @description Server-Sent Events stream of scan progress. If MCP authentication is required, the stream ends with an error event carrying code MCP_AUTH_REQUIRED, mcpAuthRequired: true, mcpUrl and urlKind, without scan_complete or a score. With `?format=audit`, the `scan_complete` event's `result` is `#/components/schemas/AuditScanResult`; every other event is unchanged. When a stored result inside the freshness window answers the request, the stream is a `kind_detected` frame followed by a terminal `scan_complete` event carrying `servedFromCache: true` and `resultAgeSeconds`, and the response carries an `Age` header. After `scan_complete`, a live scan may emit two correction events before the stream closes, both optional: `relevance_assessed` (`{ naCheckIds, reasons, score, grade }`, only when some checks are judged not applicable for this product) carries the corrected `score` and `grade`, and `summary_ready` (`{ agenticSummary }`) carries the summary. Consume events until the stream closes. Closing does not mean the analysis is final: when deep checks are still pending, the stream closes early and a background worker finishes relevance and summary later. Read GET /api/score/{domain} after the stream closes and poll it while `analysisStatus` is `partial`. When present, preserve `result.scanId` as the scanId query parameter. Managed live progress frames carry the same optional scanId after allocation, so early deep-check polling can use it. A freshness-window hit is already final and emits neither event. Event types (the `type` field), in emission order: `kind_detecting` - reachability passed and URL-kind detection is running (no payload); `kind_detected` - detection resolved: `{ kind: 'domain' | 'mcp' | 'mcp-app', mcpUrl?, embeddedMcpUrls?, hint? }`, exactly once, before any `check_start`; `discovery_phase` (optional) - a context-gathering step, or after `scan_complete` a post-scan finalize step: `{ step, label?, stepIndex?, totalSteps? }`, zero or more times; `scan_init` - the check plan: `{ layerMaxScores, totalChecks?, checkRoster?, staticOnly? }`; may be sent twice, the later one is authoritative; `check_start` - one check slot started: `{ layerId, layerName, checkId, checkName, mcpKind?, mcpUrl? }`; `check_complete` - one check slot finished: `{ layerId, layerName, checkId, checkName, status, score, maxScore, details?, bonus?, naKind?, maturity?, mcpKind?, mcpUrl? }`; `layer_complete` - every check in a layer finished: `{ layerId, layerName }`; `scan_complete` - the scored result, not the last frame: `{ result }` (AuditScanResult under `?format=audit`), plus `siteType` with `?include=siteType` and `servedFromCache` / `resultAgeSeconds` on a freshness hit; `relevance_assessed` (optional) - after `scan_complete`, only when checks were judged not applicable: `{ naCheckIds, reasons, score, grade }` with the corrected score and grade; `summary_ready` (optional) - after `scan_complete`: `{ agenticSummary }`; `error` (terminal, optional) - the scan failed and no `scan_complete` follows: `{ message }`, plus `code: 'MCP_AUTH_REQUIRED'`, `mcpAuthRequired`, `mcpUrl` and `urlKind` when an MCP server requires authentication. Read until the stream closes; only a terminal event is guaranteed to be the last frame. */
|
|
2761
3192
|
200: {
|
|
2762
3193
|
content: {
|
|
2763
3194
|
"text/event-stream": string;
|
|
@@ -2767,7 +3198,7 @@ export interface operations {
|
|
|
2767
3198
|
400: {
|
|
2768
3199
|
content: never;
|
|
2769
3200
|
};
|
|
2770
|
-
/** @description Rate limit exceeded - either the 10-per-minute burst cap or the durable daily quota (30 scans per rolling 24h per IP; 6 per day for force=1). The response carries a Retry-After header with the seconds until the caller's window frees up. */
|
|
3201
|
+
/** @description Rate limit exceeded - either the 10-per-minute burst cap or the durable daily quota (30 scans per rolling 24h per IP; 6 per day for force=1). The response carries a Retry-After header with the seconds until the caller's window frees up. A keyed caller whose key has used its daily or monthly scan limit gets 429 with error `usage_limit_reached` and `kind`, `period` (`day` or `month`), `used`, `limit`, `resets_at` and `retry_after_ms`; its Retry-After counts to `resets_at`: the next 00:00 UTC for a daily limit, the next 1st of the month (UTC) for a monthly one, and the later of the two when both are used up. That refusal is key-wide; GET /api/usage shows the numbers. */
|
|
2771
3202
|
429: {
|
|
2772
3203
|
headers: {
|
|
2773
3204
|
/** @description Seconds until next allowed request */
|
|
@@ -2800,7 +3231,7 @@ export interface operations {
|
|
|
2800
3231
|
"application/json": components["schemas"]["ErrorResponse"];
|
|
2801
3232
|
};
|
|
2802
3233
|
};
|
|
2803
|
-
/** @description Rate limit exceeded - either the 10-per-minute burst cap (body `{ error }`) or the durable daily scan budget shared with POST /api/scan (body also carries `retry_after_ms`). Both carry a Retry-After header with the seconds until the caller's window frees up. */
|
|
3234
|
+
/** @description Rate limit exceeded - either the 10-per-minute burst cap (body `{ error }`) or the durable daily scan budget shared with POST /api/scan (body also carries `retry_after_ms`). Both carry a Retry-After header with the seconds until the caller's window frees up. A keyed caller whose key has used its daily or monthly scan limit gets 429 with error `usage_limit_reached` and `kind`, `period` (`day` or `month`), `used`, `limit`, `resets_at` and `retry_after_ms`; its Retry-After counts to `resets_at`: the next 00:00 UTC for a daily limit, the next 1st of the month (UTC) for a monthly one, and the later of the two when both are used up. That refusal is key-wide; GET /api/usage shows the numbers. */
|
|
2804
3235
|
429: {
|
|
2805
3236
|
headers: {
|
|
2806
3237
|
/** @description Seconds until next allowed request */
|
|
@@ -2823,6 +3254,10 @@ export interface operations {
|
|
|
2823
3254
|
getScore: {
|
|
2824
3255
|
parameters: {
|
|
2825
3256
|
query?: {
|
|
3257
|
+
/** @description Read the exact managed scan returned by a scan response. Keep the original target and scanId when polling after a release or partner assignment changes. Only published standard or preparation scans are readable; previews are hidden. A missing or mismatched ID never falls back to the current scan. */
|
|
3258
|
+
scanId?: number;
|
|
3259
|
+
/** @description Optional. The published scoring version to use for this request. Omitted, the request uses the version pinned to your API key, else the public version. An unpublished or unknown version answers 400 `scoring_version_unavailable` listing the published versions; a value that is not a positive integer answers 400 `invalid_scoring_version`. Until release management is active, a request can name 3 (the same opt-in as the older `rankerVersion: 3`) or the version it would run anyway; any other version answers 400. A version other than the one a domain was last scanned under has no stored result yet, so the first scan of a domain under it runs live. */
|
|
3260
|
+
scoringVersion?: number;
|
|
2826
3261
|
/** @description Pass 1 to include a `competitors` object in the response: the category top-5 leaders plus the neighbor window (2 above / self / 2 below) drawn from the leaderboard. Returned only for domains with a market category - unclassified domains (Community, or no leaderboard row) get `competitors: null`. Omitted by default so the plain response stays lean. */
|
|
2827
3262
|
competitors?: "1";
|
|
2828
3263
|
/** @description Pass `audit` to receive the versioned, allowlisted audit shape (AuditScanResult / AuditScoreResult) instead of the default body: every field is documented, carries a `contractVersion`, and internal fields are dropped. Omit it and the response is unchanged from previous releases. On GET /api/scan/stream, only the `scan_complete` event's `result` is projected - all other events are identical to the default stream. */
|
|
@@ -2833,7 +3268,7 @@ export interface operations {
|
|
|
2833
3268
|
siteType?: "content" | "business" | "app" | "store";
|
|
2834
3269
|
};
|
|
2835
3270
|
path: {
|
|
2836
|
-
/** @description The domain to look up (e.g. stripe.com). URL-encoded full URLs are normalized to their hostname. */
|
|
3271
|
+
/** @description The domain to look up (e.g. stripe.com). Without scanId, URL-encoded full URLs are normalized to their hostname. With scanId, use the exact scanned target; MCP endpoints retain their full URL, including a meaningful trailing slash. */
|
|
2837
3272
|
domain: string;
|
|
2838
3273
|
};
|
|
2839
3274
|
};
|
|
@@ -2854,10 +3289,14 @@ export interface operations {
|
|
|
2854
3289
|
};
|
|
2855
3290
|
};
|
|
2856
3291
|
};
|
|
2857
|
-
/** @description
|
|
3292
|
+
/** @description The scanId is not a positive integer. */
|
|
3293
|
+
400: {
|
|
3294
|
+
content: never;
|
|
3295
|
+
};
|
|
3296
|
+
/** @description Without scanId, no cached score for this domain. With scanId, code scan_not_found means the target/ID is missing or not public; scan_result_pending means that exact scan has not written a result yet. Neither falls back to the current row. The domain miss body includes `code: "DOMAIN_NOT_SCANNED"` and a `next_action` pointing at `POST /api/scan` (`nextAction`, camelCase, under `?format=audit`). */
|
|
2858
3297
|
404: {
|
|
2859
3298
|
content: {
|
|
2860
|
-
"application/json": components["schemas"]["NotScannedResponse"];
|
|
3299
|
+
"application/json": components["schemas"]["NotScannedResponse"] | components["schemas"]["ErrorResponse"];
|
|
2861
3300
|
};
|
|
2862
3301
|
};
|
|
2863
3302
|
/** @description MCP authentication is required. No score or grade was produced. The failed attempt does not overwrite a previous measured scan. */
|
|
@@ -2880,6 +3319,45 @@ export interface operations {
|
|
|
2880
3319
|
500: {
|
|
2881
3320
|
content: never;
|
|
2882
3321
|
};
|
|
3322
|
+
/** @description The partner scoring assignment or deployed scoring rules are unavailable. */
|
|
3323
|
+
503: {
|
|
3324
|
+
content: never;
|
|
3325
|
+
};
|
|
3326
|
+
};
|
|
3327
|
+
};
|
|
3328
|
+
/**
|
|
3329
|
+
* Poll deep checks for a scan
|
|
3330
|
+
* @description Returns checks and completion state for the caller's assigned scan. Pass the scanId from the original response to keep reading that scan after an assignment changes. With scanId, domain can be the URL-encoded exact MCP endpoint. Responses are never cached.
|
|
3331
|
+
*/
|
|
3332
|
+
getDeepChecks: {
|
|
3333
|
+
parameters: {
|
|
3334
|
+
query?: {
|
|
3335
|
+
/** @description Read the exact managed scan returned by a scan response. Keep the original target and scanId when polling after a release or partner assignment changes. Only published standard or preparation scans are readable; previews are hidden. A missing or mismatched ID never falls back to the current scan. */
|
|
3336
|
+
scanId?: number;
|
|
3337
|
+
};
|
|
3338
|
+
path: {
|
|
3339
|
+
domain: string;
|
|
3340
|
+
};
|
|
3341
|
+
};
|
|
3342
|
+
responses: {
|
|
3343
|
+
/** @description The selected scan's deep-check state */
|
|
3344
|
+
200: {
|
|
3345
|
+
content: {
|
|
3346
|
+
"application/json": components["schemas"]["DeepCheckResponse"];
|
|
3347
|
+
};
|
|
3348
|
+
};
|
|
3349
|
+
/** @description Invalid scanId. */
|
|
3350
|
+
400: {
|
|
3351
|
+
content: never;
|
|
3352
|
+
};
|
|
3353
|
+
/** @description The exact scan is missing, belongs to another target, or is not public. */
|
|
3354
|
+
404: {
|
|
3355
|
+
content: never;
|
|
3356
|
+
};
|
|
3357
|
+
/** @description Scoring assignment or deep-check results unavailable. */
|
|
3358
|
+
503: {
|
|
3359
|
+
content: never;
|
|
3360
|
+
};
|
|
2883
3361
|
};
|
|
2884
3362
|
};
|
|
2885
3363
|
/**
|
|
@@ -2906,15 +3384,57 @@ export interface operations {
|
|
|
2906
3384
|
};
|
|
2907
3385
|
};
|
|
2908
3386
|
};
|
|
3387
|
+
/**
|
|
3388
|
+
* Read the rules for a published scoring version
|
|
3389
|
+
* @description Returns the scored checks, layer weights, grade thresholds and score formula for the requested version. A frozen version returns exactly the rules it was frozen with. Before managed publication, the current default and explicitly available legacy scoring versions are readable with publishedAt set to null. After managed publication, unpublished candidates are not public. No authentication required; responses use Cache-Control: no-store and Access-Control-Allow-Origin: *.
|
|
3390
|
+
*/
|
|
3391
|
+
getScoringRules: {
|
|
3392
|
+
parameters: {
|
|
3393
|
+
path: {
|
|
3394
|
+
/** @description The scoringVersion returned by a scan, score or catalog response. */
|
|
3395
|
+
version: number;
|
|
3396
|
+
};
|
|
3397
|
+
};
|
|
3398
|
+
responses: {
|
|
3399
|
+
/** @description The scoring rules */
|
|
3400
|
+
200: {
|
|
3401
|
+
content: {
|
|
3402
|
+
"application/json": components["schemas"]["ScoringRules"];
|
|
3403
|
+
};
|
|
3404
|
+
};
|
|
3405
|
+
/** @description Invalid scoring version */
|
|
3406
|
+
400: {
|
|
3407
|
+
content: never;
|
|
3408
|
+
};
|
|
3409
|
+
/** @description Unknown or unpublished scoring version */
|
|
3410
|
+
404: {
|
|
3411
|
+
content: never;
|
|
3412
|
+
};
|
|
3413
|
+
/** @description Rate limit exceeded: 60 requests per minute per IP */
|
|
3414
|
+
429: {
|
|
3415
|
+
headers: {
|
|
3416
|
+
/** @description Seconds until the next allowed request */
|
|
3417
|
+
"Retry-After"?: number;
|
|
3418
|
+
};
|
|
3419
|
+
content: never;
|
|
3420
|
+
};
|
|
3421
|
+
/** @description Rules unavailable, including a mismatch between published rules and this deployment */
|
|
3422
|
+
503: {
|
|
3423
|
+
content: never;
|
|
3424
|
+
};
|
|
3425
|
+
};
|
|
3426
|
+
};
|
|
2909
3427
|
/**
|
|
2910
3428
|
* Get the complete catalog of scanner checks
|
|
2911
|
-
* @description Returns every check the ora scanner can run - stable id, scored layer, max score, applicability, eligible scan kinds, tier, maturity, and fix guidance per check, plus the four scored layers with their weights. Check ids are stable: gate CI on an explicit id list, not on tiers (the required set can grow on a minor version). Ids are also what POST /api/scan/checks takes, and every check carries a `beta` boolean for building check pickers - a beta check runs but cannot affect any score. The
|
|
3429
|
+
* @description Returns every check the ora scanner can run - stable id, scored layer, max score, applicability, eligible scan kinds, tier, maturity, and fix guidance per check, plus the four scored layers with their weights. Check ids are stable: gate CI on an explicit id list, not on tiers (the required set can grow on a minor version). Ids are also what POST /api/scan/checks takes, and every check carries a `beta` boolean for building check pickers - a beta check runs but cannot affect any score. The catalog follows the public scoring version or the partner API key's assigned version; scoringVersion and rulesUrl identify its rules. One optional parameter: `?include=essentials` adds `essentialsTier`, `essentialsBonusOnly`, and `essentialsExcluded` (the essentials-model classification; excluded checks are ignored by that model outright) to every check; without it those fields are omitted. Sends Access-Control-Allow-Origin: *. Keyed or managed-release responses use private, no-store; anonymous legacy responses are CDN-cached for 1 hour. Rate limited to 60 requests per minute per IP - returns 429 with a Retry-After header if exceeded.
|
|
2912
3430
|
*/
|
|
2913
3431
|
listChecks: {
|
|
2914
3432
|
parameters: {
|
|
2915
3433
|
query?: {
|
|
2916
3434
|
/** @description Opt-in expansion list (comma-separated). `essentials` adds one response key, `essentials`: an alternate reading of the same scan carrying its own `score` (0-100 or null - required checks share 80 points, recommended 20, forward-looking signals upside-only), the required/recommended buckets, label copy, per-surface sub-scores, access signals, and a `checks` map keyed by check id. That map holds the essentials INTERPRETATION only (tier, bonus, fraction, occurrences, `essentialsGain`) - name, status, details, ora's recommendation, and `estScoreGain` for the same id stay in `layers[].checks[]`, so nothing serializes twice; join on the id. The pre-sorted `issues` list and `scoreEvidence` are arrays of ids resolving in that map. Omit the parameter and the response is byte-identical to previous releases. On GET /api/checks, `essentials` instead adds `essentialsTier`, `essentialsBonusOnly`, and `essentialsExcluded` to every catalog check (an excluded check never enters the essentials model; since 1.19.1 that is the two robots.txt policy checks). */
|
|
2917
3435
|
include?: "essentials";
|
|
3436
|
+
/** @description Optional. The published scoring version to use for this request. Omitted, the request uses the version pinned to your API key, else the public version. An unpublished or unknown version answers 400 `scoring_version_unavailable` listing the published versions; a value that is not a positive integer answers 400 `invalid_scoring_version`. Until release management is active, a request can name 3 (the same opt-in as the older `rankerVersion: 3`) or the version it would run anyway; any other version answers 400. A version other than the one a domain was last scanned under has no stored result yet, so the first scan of a domain under it runs live. */
|
|
3437
|
+
scoringVersion?: number;
|
|
2918
3438
|
};
|
|
2919
3439
|
};
|
|
2920
3440
|
responses: {
|
|
@@ -3081,22 +3601,24 @@ export interface operations {
|
|
|
3081
3601
|
};
|
|
3082
3602
|
/**
|
|
3083
3603
|
* Search agentic resources (Agentic Resource Discovery)
|
|
3084
|
-
* @description Runs an Agentic Resource Discovery (ARD) search over ora's catalog of agent-ready resources. Returns resources ranked by relevance to a free-text query, with optional field filters and federation control. The per-result `score` is
|
|
3604
|
+
* @description Runs an Agentic Resource Discovery (ARD) search over ora's catalog of agent-ready resources. Returns resources ranked by relevance to a free-text query, with optional field filters and federation control. The per-result `score` is pure relevance (0-100): match quality for the query, never a trust or readiness rating. Results are ordered by relevance with agent-readiness reordering close matches, so `score` need not decrease down the list; the readiness itself is in `oraScorecard` and GET /api/score/{domain}. Rate limited to 30 requests per minute per IP - returns 429 if exceeded.
|
|
3085
3605
|
*/
|
|
3086
3606
|
ardSearch: {
|
|
3087
3607
|
requestBody: {
|
|
3088
3608
|
content: {
|
|
3089
3609
|
"application/json": {
|
|
3090
3610
|
query: {
|
|
3611
|
+
/** @description Optional JSON-LD context (a string, object or array, at most 4096 characters serialized). Accepted per ARD v0.91; ora binds no additional filter keys from it. */
|
|
3612
|
+
"@context"?: unknown;
|
|
3091
3613
|
/** @description Free-text search query. May be omitted when filter is present (a filter-only browse); at least one of text/filter is required. */
|
|
3092
3614
|
text?: string;
|
|
3093
|
-
/** @description Optional field filters: a map of field name to an allowed value (a scalar string or an array of strings; OR within a key, AND across keys). */
|
|
3615
|
+
/** @description Optional field filters: a map of field name to an allowed value (a scalar string or an array of strings; OR within a key, AND across keys). Keys: type, identifier, displayName, tags, capabilities, version, publisher (derived from the URN identifier), and literal dot-paths under trustManifest.* and metadata.* (a path crossing an array matches when any element does). Any other key returns 400 INVALID_ARGUMENT. */
|
|
3094
3616
|
filter?: {
|
|
3095
3617
|
[key: string]: string | string[];
|
|
3096
3618
|
};
|
|
3097
3619
|
};
|
|
3098
3620
|
/**
|
|
3099
|
-
* @description Federation policy. 'none': ora's own index only. 'referrals': ora's results plus referrals[] pointers to upstream registries. 'auto': ora merges upstream registry results into results (each tagged with its upstream source); merging is off by default (server-gated) and
|
|
3621
|
+
* @description Federation policy. 'none': ora's own index only. 'referrals': ora's results plus referrals[] pointers to upstream registries. 'auto': ora merges upstream registry results into results (each tagged with its upstream source); merging is off by default (server-gated), and while it is off 'auto' returns referrals[] as 'referrals' does.
|
|
3100
3622
|
* @default auto
|
|
3101
3623
|
* @enum {string}
|
|
3102
3624
|
*/
|
|
@@ -3106,13 +3628,13 @@ export interface operations {
|
|
|
3106
3628
|
* @default 10
|
|
3107
3629
|
*/
|
|
3108
3630
|
pageSize?: number;
|
|
3109
|
-
/** @description Opaque pagination token from a previous response. */
|
|
3631
|
+
/** @description Opaque pagination token from a previous response. A token ora did not issue returns 400 INVALID_ARGUMENT. */
|
|
3110
3632
|
pageToken?: string;
|
|
3111
3633
|
};
|
|
3112
3634
|
};
|
|
3113
3635
|
};
|
|
3114
3636
|
responses: {
|
|
3115
|
-
/** @description The ARD SearchResponse: { results, referrals, pageToken? }. pageToken is omitted when the result set is exhausted (never null).
|
|
3637
|
+
/** @description The ARD SearchResponse: { results, referrals, pageToken? }. pageToken is omitted when the result set is exhausted (never null). referrals lists upstream registries in 'referrals' mode, and in 'auto' mode while upstream merging is off. Each result's trustManifest.attestations[0] is a reference { type, uri, mediaType } to GET /api/ard/attestation/{domain}, not inlined claims. Results from ora's own index also carry an `oraScorecard` vendor extension ({ score?, grade?, category?, checkedAt? }): agent-readiness score/grade only when ora has scored the domain (never a fabricated 0/F), category whenever ora has classified it - all distinct from the relevance `score`; the signed claim remains the attestation endpoint. Ora product entries (type application/vnd.ora.product+json) reference the JSON score document GET /api/score/{domain} as their url when scored, or carry inline data { domain, name, category?, status: 'not_scanned' } when not, with the human report page in `oraReportUrl`; skill entries use application/agent-skills+md (a type filter on the earlier application/ai-skill+md matches too). Entries crawled from other publishers' catalogs carry `oraPublisherBinding`: 'verified' when the entry's urn:air publisher is the site ora crawled it from, else 'unverified' (ARD §4.5.1); an unverified entry carries no trustManifest and sorts after verified ones at equal relevance. */
|
|
3116
3638
|
200: {
|
|
3117
3639
|
content: never;
|
|
3118
3640
|
};
|
|
@@ -3138,7 +3660,7 @@ export interface operations {
|
|
|
3138
3660
|
};
|
|
3139
3661
|
/**
|
|
3140
3662
|
* Faceted exploration of agentic resources (Agentic Resource Discovery)
|
|
3141
|
-
* @description Returns facet aggregations (counts per field value) for an Agentic Resource Discovery (ARD) result set. Use this to build filter UIs over the ARD catalog. An optional query narrows the set before faceting. Rate limited to 30 requests per minute per IP - returns 429 if exceeded.
|
|
3663
|
+
* @description Returns facet aggregations (counts per field value) for an Agentic Resource Discovery (ARD) result set. Use this to build filter UIs over the ARD catalog. A `type` bucket's value is the raw media type, so it can be used as a filter value as-is. An optional query narrows the set before faceting: with text, the set is exactly what POST /api/ard/search matches for the same text and filter; without it, the whole index narrowed by the filter. Rate limited to 30 requests per minute per IP - returns 429 if exceeded.
|
|
3142
3664
|
*/
|
|
3143
3665
|
ardExplore: {
|
|
3144
3666
|
requestBody: {
|
|
@@ -3146,15 +3668,18 @@ export interface operations {
|
|
|
3146
3668
|
"application/json": {
|
|
3147
3669
|
/** @description Optional query to narrow the set before faceting (same shape as POST /api/ard/search's query). */
|
|
3148
3670
|
query?: {
|
|
3671
|
+
/** @description Optional JSON-LD context, as on POST /api/ard/search. */
|
|
3672
|
+
"@context"?: unknown;
|
|
3149
3673
|
/** @description Free-text search query. */
|
|
3150
3674
|
text?: string;
|
|
3675
|
+
/** @description Same keys as POST /api/ard/search's filter; an unsupported key returns 400 INVALID_ARGUMENT. */
|
|
3151
3676
|
filter?: {
|
|
3152
3677
|
[key: string]: string[];
|
|
3153
3678
|
};
|
|
3154
3679
|
};
|
|
3155
3680
|
resultType: {
|
|
3156
3681
|
facets: {
|
|
3157
|
-
/** @description The resource field to aggregate on. */
|
|
3682
|
+
/** @description The resource field to aggregate on: any search filter key, or category. An unsupported field returns 400 INVALID_ARGUMENT. */
|
|
3158
3683
|
field: string;
|
|
3159
3684
|
/** @description Max facet values to return for this field. */
|
|
3160
3685
|
limit?: number;
|
|
@@ -3197,11 +3722,11 @@ export interface operations {
|
|
|
3197
3722
|
ardListAgents: {
|
|
3198
3723
|
parameters: {
|
|
3199
3724
|
query?: {
|
|
3200
|
-
/** @description Results per page (1-100, default 20). */
|
|
3725
|
+
/** @description Results per page (1-100, default 20). A larger value clamps to 100; a non-positive or non-integer value returns 400 INVALID_ARGUMENT. */
|
|
3201
3726
|
pageSize?: number;
|
|
3202
|
-
/** @description Opaque pagination token from a previous response. */
|
|
3727
|
+
/** @description Opaque pagination token from a previous response. A token ora did not issue returns 400 INVALID_ARGUMENT. */
|
|
3203
3728
|
pageToken?: string;
|
|
3204
|
-
/** @description EBNF filter expression, e.g. "type = 'application/mcp-server-card+json' AND updatedAfter > '2026-01-01'". Fields: type, displayName, publisherId, tags, updatedAt. Operators: = != > < >= <=, conditions joined by AND. An unsupported field/operator/syntax returns 400 INVALID_ARGUMENT. */
|
|
3729
|
+
/** @description EBNF filter expression, e.g. "type = 'application/mcp-server-card+json' AND updatedAfter > '2026-01-01'". Fields: type, displayName, publisherId, tags, updatedAt (and updatedAfter / updatedBefore). Operators: = != > < >= <=, conditions joined by AND; a comma-separated type, publisherId or tags value means OR. An unsupported field/operator/syntax (createdAfter included) returns 400 INVALID_ARGUMENT. */
|
|
3205
3730
|
filter?: string;
|
|
3206
3731
|
/** @description Sort expression "<field> [ASC|DESC]", e.g. "displayName DESC". Fields: displayName, updatedAt, identifier, type. */
|
|
3207
3732
|
orderBy?: string;
|
|
@@ -3322,7 +3847,7 @@ export interface operations {
|
|
|
3322
3847
|
};
|
|
3323
3848
|
/**
|
|
3324
3849
|
* Draft a domain's own agent discovery files (ard.json, ai-catalog.json, poppy.json)
|
|
3325
|
-
* @description Drafts the agent discovery files a domain publishes about itself: /.well-known/ard.json (Agentic Resource Discovery), /.well-known/ai-catalog.json (the same catalog at the AI Catalog Standard's path) and /.well-known/poppy.json (Personal Agent Protocol,
|
|
3850
|
+
* @description Drafts the agent discovery files a domain publishes about itself: /.well-known/ard.json (Agentic Resource Discovery), /.well-known/ai-catalog.json (the same catalog at the AI Catalog Standard's path) and /.well-known/poppy.json (Personal Agent Protocol 1.0, the latest published version). Built from what ora already holds for the domain - no live crawl - so a domain ora never scanned still gets a valid minimal set (a catalog listing its website, a poppy.json for signed-out browsing) with scannedAt null. Every catalog entry is anchored to the domain itself (urn:air:<domain>:..., identity https://<domain>), never to ora, and carries only https URLs on the domain or its subdomains: anything the scan saw on another host is named in the file's notes instead. MCP servers are listed by their server card (the card the scan found, else the reserved <server-url>/server-card location, which the notes ask the owner to serve). The poppy.json is the minimal valid document; what ora saw that a fuller one could name (an OAuth issuer, MCP servers, an OpenAPI description) is listed in that file's notes. Pass ?include= for llms.txt, an edit of the site's robots.txt, an RFC 9727 api-catalog and draft MCP server cards. Review every file before publishing it. A leading www. is dropped, and any spelling other than the canonical domain answers 308 to /api/agent-files/<domain>. Sends Access-Control-Allow-Origin: * and is CDN-cached. Rate limited to 60 requests per minute per IP - returns 429 if exceeded. Also used by the generator page at directory.ora.ai/generate and by `npx ax generate-files <domain>`.
|
|
3326
3851
|
*/
|
|
3327
3852
|
generateAgentFiles: {
|
|
3328
3853
|
parameters: {
|
|
@@ -3443,7 +3968,7 @@ export interface operations {
|
|
|
3443
3968
|
};
|
|
3444
3969
|
};
|
|
3445
3970
|
responses: {
|
|
3446
|
-
/** @description Per-target cap hit - the freshness analog, not an error: the body is the most recent stored run for this exact (domain, intent, harness, model) target, marked `rate_limited: true`, so CI and agents get the newest result without spending a run. When the served run has finished, the body also carries `verdict` and `
|
|
3971
|
+
/** @description Per-target cap hit - the freshness analog, not an error: the body is the most recent stored run for this exact (domain, intent, harness, model) target, marked `rate_limited: true`, so CI and agents get the newest result without spending a run. When the served run has finished, the body also carries `verdict`, `step_count` and `flags`. Replay it via its `stream_url`. `next_action` names the one request to send next: the run itself, for its full result, once it succeeded; its stream while it is running or for 15 minutes after it failed. Anonymous tier only: a keyed caller skips the per-target cap and never receives this response. */
|
|
3447
3972
|
200: {
|
|
3448
3973
|
headers: {
|
|
3449
3974
|
/** @description Seconds until the target's oldest in-window run ages out */
|
|
@@ -3459,7 +3984,7 @@ export interface operations {
|
|
|
3459
3984
|
"application/json": components["schemas"]["JourneyCappedRun"];
|
|
3460
3985
|
};
|
|
3461
3986
|
};
|
|
3462
|
-
/** @description Run created and dispatched. Open `stream_url` (SSE) and hold it to its `result` or `error` frame: the stream is what saves the finished run, which GET /api/journey/runs/{id} then reads. A keyed custom run gets its own free text back as `intent` here - the create response is the only place any intent text is published, so GET /api/journey/runs/{id} and the capped 200 never carry it, and a curated run has no `intent` at all. */
|
|
3987
|
+
/** @description Run created and dispatched. Open `stream_url` (SSE) and hold it to its `result` or `error` frame: the stream is what saves the finished run, which GET /api/journey/runs/{id} then reads. `next_action` names that same stream as the one request to send next. A keyed custom run gets its own free text back as `intent` here - the create response is the only place any intent text is published, so GET /api/journey/runs/{id} and the capped 200 never carry it, and a curated run has no `intent` at all. */
|
|
3463
3988
|
201: {
|
|
3464
3989
|
headers: {
|
|
3465
3990
|
/** @description Size of the one window this response describes: the per-target window (100 runs per rolling 24h) for an anonymous caller, the per-key caller window (1000 runs per rolling 24h) for a keyed one */
|
|
@@ -3473,39 +3998,51 @@ export interface operations {
|
|
|
3473
3998
|
"application/json": components["schemas"]["JourneyCreatedRun"];
|
|
3474
3999
|
};
|
|
3475
4000
|
};
|
|
3476
|
-
/** @description Invalid input: schema failure (including unknown body fields - the contract is strict, and a body matching neither intent arm or both of them lands here), `code: "INVALID_DOMAIN"` for a domain the scanner would reject, or `code: "UNSUPPORTED_AGENT"` for a (harness, model) pair that is not publicly runnable. */
|
|
4001
|
+
/** @description Invalid input: schema failure (including unknown body fields - the contract is strict, and a body matching neither intent arm or both of them lands here), `code: "INVALID_DOMAIN"` for a domain the scanner would reject, or `code: "UNSUPPORTED_AGENT"` for a (harness, model) pair that is not publicly runnable. The two coded refusals carry `next_action`: the request to send again with a public host, or GET /api/journey/agents. */
|
|
3477
4002
|
400: {
|
|
3478
4003
|
content: {
|
|
3479
|
-
"application/json": components["schemas"]["ErrorResponse"]
|
|
4004
|
+
"application/json": components["schemas"]["ErrorResponse"] & {
|
|
4005
|
+
/** @description The one request to send next. 400 INVALID_DOMAIN: the same request with a public host as intent.domain. 400 UNSUPPORTED_AGENT: GET /api/journey/agents, to pick an agent that runs here. 401: the docs page that says how to get a partner key. 429 and 503: the same request again after `wait_seconds`. Absent on a schema failure and on a `usage_limit_reached` 429. */
|
|
4006
|
+
next_action?: components["schemas"]["JourneyNextAction"];
|
|
4007
|
+
};
|
|
3480
4008
|
};
|
|
3481
4009
|
};
|
|
3482
|
-
/** @description `code: "CUSTOM_INTENT_REQUIRES_KEY"` - the request sent a custom free-text intent without a recognized ora-issued partner API key. An absent, malformed, and unrecognized key all land here alike, so the status never doubles as a key-validity oracle. Two ways forward: run a curated intent instead (GET /api/journey/intents lists them, and that arm needs no key), or ask ora for a partner key - they are issued manually on request, so contact us at the address in this document's info.contact. */
|
|
4010
|
+
/** @description `code: "CUSTOM_INTENT_REQUIRES_KEY"` - the request sent a custom free-text intent without a recognized ora-issued partner API key. An absent, malformed, and unrecognized key all land here alike, so the status never doubles as a key-validity oracle. Two ways forward: run a curated intent instead (GET /api/journey/intents lists them, and that arm needs no key), or ask ora for a partner key - they are issued manually on request, so contact us at the address in this document's info.contact. `next_action` points at the docs page that says how to get one. */
|
|
3483
4011
|
401: {
|
|
3484
4012
|
content: {
|
|
3485
|
-
"application/json": components["schemas"]["ErrorResponse"]
|
|
4013
|
+
"application/json": components["schemas"]["ErrorResponse"] & {
|
|
4014
|
+
/** @description The one request to send next. 400 INVALID_DOMAIN: the same request with a public host as intent.domain. 400 UNSUPPORTED_AGENT: GET /api/journey/agents, to pick an agent that runs here. 401: the docs page that says how to get a partner key. 429 and 503: the same request again after `wait_seconds`. Absent on a schema failure and on a `usage_limit_reached` 429. */
|
|
4015
|
+
next_action?: components["schemas"]["JourneyNextAction"];
|
|
4016
|
+
};
|
|
3486
4017
|
};
|
|
3487
4018
|
};
|
|
3488
|
-
/** @description Caller limit exceeded - the 20-per-minute burst cap (anonymous callers only; a keyed caller skips it), or the durable per-caller budget (20 runs per rolling 24h per IP anonymous, plus 3000 per rolling 24h shared by all anonymous callers, 1000 per rolling 24h per key; body carries `retry_after_ms`). Per-TARGET saturation is the 200 above, not this. */
|
|
4019
|
+
/** @description Caller limit exceeded - the 20-per-minute burst cap (anonymous callers only; a keyed caller skips it), or the durable per-caller budget (20 runs per rolling 24h per IP anonymous, plus 3000 per rolling 24h shared by all anonymous callers, 1000 per rolling 24h per key; body carries `retry_after_ms`). Per-TARGET saturation is the 200 above, not this. A keyed caller whose key has used its daily or monthly journey limit gets 429 with error `usage_limit_reached` and `kind`, `period` (`day` or `month`), `used`, `limit`, `resets_at` and `retry_after_ms`; its Retry-After counts to `resets_at`: the next 00:00 UTC for a daily limit, the next 1st of the month (UTC) for a monthly one, and the later of the two when both are used up. That refusal is key-wide; GET /api/usage shows the numbers. The burst and per-caller refusals carry `next_action`: the same request again after `wait_seconds`; the `usage_limit_reached` refusal carries none. */
|
|
3489
4020
|
429: {
|
|
3490
4021
|
headers: {
|
|
3491
4022
|
/** @description Seconds until next allowed request */
|
|
3492
4023
|
"Retry-After"?: number;
|
|
3493
4024
|
};
|
|
3494
4025
|
content: {
|
|
3495
|
-
"application/json": components["schemas"]["ErrorResponse"]
|
|
4026
|
+
"application/json": components["schemas"]["ErrorResponse"] & {
|
|
4027
|
+
/** @description The one request to send next. 400 INVALID_DOMAIN: the same request with a public host as intent.domain. 400 UNSUPPORTED_AGENT: GET /api/journey/agents, to pick an agent that runs here. 401: the docs page that says how to get a partner key. 429 and 503: the same request again after `wait_seconds`. Absent on a schema failure and on a `usage_limit_reached` 429. */
|
|
4028
|
+
next_action?: components["schemas"]["JourneyNextAction"];
|
|
4029
|
+
};
|
|
3496
4030
|
};
|
|
3497
4031
|
};
|
|
3498
|
-
/** @description The run engine could not be reached; nothing was created or consumed. */
|
|
4032
|
+
/** @description The run engine could not be reached; nothing was created or consumed. `next_action` is the same request again after `wait_seconds` (about a minute). */
|
|
3499
4033
|
503: {
|
|
3500
4034
|
content: {
|
|
3501
|
-
"application/json": components["schemas"]["ErrorResponse"]
|
|
4035
|
+
"application/json": components["schemas"]["ErrorResponse"] & {
|
|
4036
|
+
/** @description The one request to send next. 400 INVALID_DOMAIN: the same request with a public host as intent.domain. 400 UNSUPPORTED_AGENT: GET /api/journey/agents, to pick an agent that runs here. 401: the docs page that says how to get a partner key. 429 and 503: the same request again after `wait_seconds`. Absent on a schema failure and on a `usage_limit_reached` 429. */
|
|
4037
|
+
next_action?: components["schemas"]["JourneyNextAction"];
|
|
4038
|
+
};
|
|
3502
4039
|
};
|
|
3503
4040
|
};
|
|
3504
4041
|
};
|
|
3505
4042
|
};
|
|
3506
4043
|
/**
|
|
3507
4044
|
* Get a journey run record (non-streaming)
|
|
3508
|
-
* @description Returns the run record by id. While the run executes, `status` is 'running' - open the stream or poll. Once finished and persisted, `status` is 'succeeded' and the body carries `verdict`, `step_count` (billable steps - the same counter run pricing uses), and the full `result` (trajectory + insight + signals). `status` 'failed' is terminal with no result. `result` is present iff status is 'succeeded'.
|
|
4045
|
+
* @description Returns the run record by id. While the run executes, `status` is 'running' - open the stream or poll. Once finished and persisted, `status` is 'succeeded' and the body carries `verdict`, `step_count` (billable steps - the same counter run pricing uses), `flags` (two notes beside the verdict that never change it: `blocked` when the site refused the agent, `answered_from_memory` when half or more of the answer came from the model's memory), and the full `result` (trajectory + insight + signals). `status` 'failed' is terminal with no result. `result` is present iff status is 'succeeded'. `next_action` names the one request to send next: the run's stream while it is running, and for 15 minutes after it failed, since reopening it reconnects a run that only lost its connection. A succeeded run carries none, and neither does one that failed longer ago, which is final.
|
|
3509
4046
|
*/
|
|
3510
4047
|
getJourneyRun: {
|
|
3511
4048
|
parameters: {
|
|
@@ -3515,7 +4052,7 @@ export interface operations {
|
|
|
3515
4052
|
};
|
|
3516
4053
|
};
|
|
3517
4054
|
responses: {
|
|
3518
|
-
/** @description The run record; plus `result` once succeeded. */
|
|
4055
|
+
/** @description The run record; plus `result` and `flags` once succeeded, and `next_action` until then. */
|
|
3519
4056
|
200: {
|
|
3520
4057
|
content: {
|
|
3521
4058
|
"application/json": components["schemas"]["JourneyRunDetail"];
|
|
@@ -3529,7 +4066,7 @@ export interface operations {
|
|
|
3529
4066
|
};
|
|
3530
4067
|
/**
|
|
3531
4068
|
* Get or create a domain's agent journey
|
|
3532
|
-
* @description Returns the agent journey for a domain, running one only if there is not one already. Send only the domain and no body: ora selects the intent and the agent. Requires an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora); without one, 401 PARTNER_KEY_REQUIRED. 200 means nothing was dispatched and an existing run answered, either finished (carrying its `result`) or still running (open `stream_url` to watch it). 201 means a new run was dispatched. Branch on `dispatched`. Two response views (see the `view` parameter): `graph` (JourneyDomainRunGraph, the default - `result` narrowed to what drawing the journey needs) and `full` (JourneyDomainRun, the complete projection, on `?view=full`). A finished run is served indefinitely; `run_age_seconds` gives its age. There is no per-caller rate limit on this endpoint. Each domain is capped at 100 runs per rolling 24h, and one domain cannot start two runs at once - both are per-domain, neither limits how many domains you may ask for or how fast.
|
|
4069
|
+
* @description Returns the agent journey for a domain, running one only if there is not one already. Send only the domain and no body: ora selects the intent and the agent. Requires an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora); without one, 401 PARTNER_KEY_REQUIRED. 200 means nothing was dispatched and an existing run answered, either finished (carrying its `result`) or still running (open `stream_url` to watch it). 201 means a new run was dispatched. Branch on `dispatched`. Two response views (see the `view` parameter): `graph` (JourneyDomainRunGraph, the default - `result` narrowed to what drawing the journey needs) and `full` (JourneyDomainRun, the complete projection, on `?view=full`). A finished run is served indefinitely; `run_age_seconds` gives its age. There is no per-caller rate limit on this endpoint, except a daily or monthly journey usage limit when the key carries one. Each domain is capped at 100 runs per rolling 24h, and one domain cannot start two runs at once - both are per-domain, neither limits how many domains you may ask for or how fast.
|
|
3533
4070
|
*/
|
|
3534
4071
|
getOrCreateDomainJourney: {
|
|
3535
4072
|
parameters: {
|
|
@@ -3543,7 +4080,7 @@ export interface operations {
|
|
|
3543
4080
|
};
|
|
3544
4081
|
};
|
|
3545
4082
|
responses: {
|
|
3546
|
-
/** @description An existing run answered; nothing was dispatched (`dispatched` is false). Either a finished run with `result` and `run_age_seconds` (final: no backoff hint), one still running (carries `retry_after_ms` and a `Retry-After` header: poll no faster than that), or - when the domain is over its 100-per-24h cap - its newest stored run with `retry_after_ms`. The body is JourneyDomainRun, or JourneyDomainRunGraph when the effective view is `graph` (see the `view` parameter). */
|
|
4083
|
+
/** @description An existing run answered; nothing was dispatched (`dispatched` is false). Either a finished run with `result`, `flags` and `run_age_seconds` (final: no backoff hint), one still running (carries `retry_after_ms` and a `Retry-After` header: poll no faster than that), or - when the domain is over its 100-per-24h cap - its newest stored run with `retry_after_ms`. The body is JourneyDomainRun, or JourneyDomainRunGraph when the effective view is `graph` (see the `view` parameter). */
|
|
3547
4084
|
200: {
|
|
3548
4085
|
content: {
|
|
3549
4086
|
"application/json": components["schemas"]["JourneyDomainRun"] | components["schemas"]["JourneyDomainRunGraph"];
|
|
@@ -3567,7 +4104,7 @@ export interface operations {
|
|
|
3567
4104
|
"application/json": components["schemas"]["ErrorResponse"];
|
|
3568
4105
|
};
|
|
3569
4106
|
};
|
|
3570
|
-
/** @description Back off and retry the SAME DOMAIN; the body carries `retry_after_ms` and a `Retry-After` header. All three codes here are per-domain, never key-wide, so do not throttle your other traffic. `POLL_TOO_FAST`: more than 3 requests for this domain inside 2 seconds; back off by this response's `retry_after_ms`. The in-flight `200` also carries `retry_after_ms`, and a poller that honours it never sees this code. `DISPATCH_IN_PROGRESS`: another request is already starting this domain. `TARGET_CAPPED`: this domain is over its 100-per-24h cap. */
|
|
4107
|
+
/** @description Back off and retry the SAME DOMAIN; the body carries `retry_after_ms` and a `Retry-After` header. All three codes here are per-domain, never key-wide, so do not throttle your other traffic. `POLL_TOO_FAST`: more than 3 requests for this domain inside 2 seconds; back off by this response's `retry_after_ms`. The in-flight `200` also carries `retry_after_ms`, and a poller that honours it never sees this code. `DISPATCH_IN_PROGRESS`: another request is already starting this domain. `TARGET_CAPPED`: this domain is over its 100-per-24h cap. One refusal here is key-wide instead: `error: "usage_limit_reached"` (no `code`) means the key has used its daily or monthly journey limit, with `kind`, `period` (`day` or `month`), `used`, `limit`, `resets_at` and `retry_after_ms` in the body and a Retry-After that counts to `resets_at`; stop dispatching journeys until then. GET /api/usage shows the numbers. */
|
|
3571
4108
|
429: {
|
|
3572
4109
|
headers: {
|
|
3573
4110
|
/** @description Seconds until next allowed request */
|
|
@@ -3677,6 +4214,42 @@ export interface operations {
|
|
|
3677
4214
|
};
|
|
3678
4215
|
};
|
|
3679
4216
|
};
|
|
4217
|
+
/**
|
|
4218
|
+
* Read your partner API key's usage and usage limits
|
|
4219
|
+
* @description Returns the calling key's own usage for the current period, per kind (scans, journeys) and per period (`day`, the calendar day in UTC, and `month`, the calendar month in UTC): how many new dispatches the key started since period_start, its limit, what remains, and when the count resets. Cached and stored answers are not counted. limit and remaining are null when the key has no limit for that kind; a key with no limit is never refused for usage. Requires an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora); the key is read from the token, so a caller can only see its own numbers. Every response carries Cache-Control: no-store. Rate limited to 60 requests per minute per key.
|
|
4220
|
+
*/
|
|
4221
|
+
getKeyUsage: {
|
|
4222
|
+
responses: {
|
|
4223
|
+
/** @description The key's usage, limits and reset time. */
|
|
4224
|
+
200: {
|
|
4225
|
+
content: {
|
|
4226
|
+
"application/json": components["schemas"]["KeyUsage"];
|
|
4227
|
+
};
|
|
4228
|
+
};
|
|
4229
|
+
/** @description `code: "PARTNER_KEY_REQUIRED"` - no recognized partner API key. An absent, malformed and unrecognized key all answer the same way. */
|
|
4230
|
+
401: {
|
|
4231
|
+
content: {
|
|
4232
|
+
"application/json": components["schemas"]["ErrorResponse"];
|
|
4233
|
+
};
|
|
4234
|
+
};
|
|
4235
|
+
/** @description `code: "RATE_LIMITED"` - more than 60 requests in a minute from this address, or for this key. */
|
|
4236
|
+
429: {
|
|
4237
|
+
headers: {
|
|
4238
|
+
/** @description Seconds until next allowed request */
|
|
4239
|
+
"Retry-After"?: number;
|
|
4240
|
+
};
|
|
4241
|
+
content: {
|
|
4242
|
+
"application/json": components["schemas"]["ErrorResponse"];
|
|
4243
|
+
};
|
|
4244
|
+
};
|
|
4245
|
+
/** @description `code: "USAGE_UNAVAILABLE"` - usage could not be read right now. Retry shortly; the route never answers a guessed zero. */
|
|
4246
|
+
503: {
|
|
4247
|
+
content: {
|
|
4248
|
+
"application/json": components["schemas"]["ErrorResponse"];
|
|
4249
|
+
};
|
|
4250
|
+
};
|
|
4251
|
+
};
|
|
4252
|
+
};
|
|
3680
4253
|
/**
|
|
3681
4254
|
* Get agent feedback for a product
|
|
3682
4255
|
* @description Returns feedback submitted by AI agents about their experience using a product. Includes aggregate stats and individual reviews.
|