ax 0.10.3 → 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/skills.d.ts +19 -0
- package/dist/contract/index.d.ts +1 -0
- package/dist/contract/types.gen.d.ts +509 -39
- package/dist/contract/version.d.ts +1 -1
- package/dist/env.d.ts +24 -0
- package/dist/index.cjs +145 -25
- package/dist/index.js +145 -25
- package/dist/main.cjs +227 -79
- package/package.json +1 -1
|
@@ -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
|
};
|
|
@@ -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, except a 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.
|
|
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
|
};
|
|
@@ -206,7 +220,7 @@ export interface paths {
|
|
|
206
220
|
"/api/usage": {
|
|
207
221
|
/**
|
|
208
222
|
* Read your partner API key's usage and usage limits
|
|
209
|
-
* @description Returns the calling key's own usage for the current period, per kind (scans, journeys) and per period (
|
|
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.
|
|
210
224
|
*/
|
|
211
225
|
get: operations["getKeyUsage"];
|
|
212
226
|
};
|
|
@@ -348,6 +362,11 @@ export interface components {
|
|
|
348
362
|
recommendation?: string;
|
|
349
363
|
/** @description Why this check does not apply to this product - it is skipped, not a deduction */
|
|
350
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";
|
|
351
370
|
};
|
|
352
371
|
AuditLayer: {
|
|
353
372
|
/** @description Layer id: discovery | accessibility | usability | payments (historical scans may carry retired ids) */
|
|
@@ -386,9 +405,25 @@ export interface components {
|
|
|
386
405
|
recommendation?: string;
|
|
387
406
|
/** @description Why this check does not apply to this product - it is skipped, not a deduction */
|
|
388
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";
|
|
389
413
|
})[];
|
|
390
414
|
};
|
|
391
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;
|
|
392
427
|
domain: string;
|
|
393
428
|
name: string;
|
|
394
429
|
score: number;
|
|
@@ -516,6 +551,11 @@ export interface components {
|
|
|
516
551
|
recommendation?: string;
|
|
517
552
|
/** @description Why this check does not apply to this product - it is skipped, not a deduction */
|
|
518
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";
|
|
519
559
|
})[];
|
|
520
560
|
})[];
|
|
521
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. */
|
|
@@ -546,7 +586,7 @@ export interface components {
|
|
|
546
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.
|
|
547
587
|
* @enum {string}
|
|
548
588
|
*/
|
|
549
|
-
contractVersion: "1.
|
|
589
|
+
contractVersion: "1.42.0";
|
|
550
590
|
/**
|
|
551
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.
|
|
552
592
|
* @enum {boolean}
|
|
@@ -594,6 +634,17 @@ export interface components {
|
|
|
594
634
|
} | null;
|
|
595
635
|
};
|
|
596
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;
|
|
597
648
|
domain: string;
|
|
598
649
|
name: string;
|
|
599
650
|
score: number;
|
|
@@ -719,6 +770,11 @@ export interface components {
|
|
|
719
770
|
recommendation?: string;
|
|
720
771
|
/** @description Why this check does not apply to this product - it is skipped, not a deduction */
|
|
721
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";
|
|
722
778
|
})[];
|
|
723
779
|
})[];
|
|
724
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. */
|
|
@@ -749,7 +805,7 @@ export interface components {
|
|
|
749
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.
|
|
750
806
|
* @enum {string}
|
|
751
807
|
*/
|
|
752
|
-
contractVersion: "1.
|
|
808
|
+
contractVersion: "1.42.0";
|
|
753
809
|
/** @description Wall-clock duration of the scan that produced this stored result */
|
|
754
810
|
durationMs: number | null;
|
|
755
811
|
/**
|
|
@@ -793,11 +849,20 @@ export interface components {
|
|
|
793
849
|
};
|
|
794
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. */
|
|
795
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;
|
|
796
861
|
/**
|
|
797
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.
|
|
798
863
|
* @enum {string}
|
|
799
864
|
*/
|
|
800
|
-
contractVersion: "1.
|
|
865
|
+
contractVersion: "1.42.0";
|
|
801
866
|
/** @description The four scored layers in scoring order, with display name and current weight. */
|
|
802
867
|
layers: {
|
|
803
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'. */
|
|
@@ -889,14 +954,27 @@ export interface components {
|
|
|
889
954
|
checkIds: string[];
|
|
890
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. */
|
|
891
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;
|
|
892
959
|
};
|
|
893
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. */
|
|
894
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;
|
|
895
973
|
/**
|
|
896
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.
|
|
897
975
|
* @enum {string}
|
|
898
976
|
*/
|
|
899
|
-
contractVersion: "1.
|
|
977
|
+
contractVersion: "1.42.0";
|
|
900
978
|
/** @description The apex domain derived from the requested URL. */
|
|
901
979
|
domain: string;
|
|
902
980
|
/** @description The normalized URL the run targeted. */
|
|
@@ -931,6 +1009,11 @@ export interface components {
|
|
|
931
1009
|
recommendation?: string;
|
|
932
1010
|
/** @description Why the check did not apply. Present on 'na' results, including requested ids that cannot apply to the detected kind. */
|
|
933
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";
|
|
934
1017
|
/**
|
|
935
1018
|
* @description The classification of the MCP surface this entry scored against - one of: product | docs | other | app. Present on MCP fan-out entries.
|
|
936
1019
|
* @enum {string}
|
|
@@ -969,6 +1052,23 @@ export interface components {
|
|
|
969
1052
|
verdict?: "satisfied" | "partial" | "unsatisfied" | "not_gradable";
|
|
970
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. */
|
|
971
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
|
+
};
|
|
972
1072
|
/** @description Journey/audit contract version (shared SemVer; see docs) */
|
|
973
1073
|
contractVersion: string;
|
|
974
1074
|
};
|
|
@@ -1002,10 +1102,45 @@ export interface components {
|
|
|
1002
1102
|
verdict?: "satisfied" | "partial" | "unsatisfied" | "not_gradable";
|
|
1003
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. */
|
|
1004
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
|
+
};
|
|
1005
1122
|
/** @description Journey/audit contract version (shared SemVer; see docs) */
|
|
1006
1123
|
contractVersion: string;
|
|
1007
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. */
|
|
1008
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
|
+
};
|
|
1009
1144
|
};
|
|
1010
1145
|
JourneyCappedRun: {
|
|
1011
1146
|
/** @description Run id - the handle for GET /api/journey/runs/{id} and the stream */
|
|
@@ -1037,6 +1172,23 @@ export interface components {
|
|
|
1037
1172
|
verdict?: "satisfied" | "partial" | "unsatisfied" | "not_gradable";
|
|
1038
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. */
|
|
1039
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
|
+
};
|
|
1040
1192
|
/** @description Journey/audit contract version (shared SemVer; see docs) */
|
|
1041
1193
|
contractVersion: string;
|
|
1042
1194
|
/**
|
|
@@ -1053,6 +1205,24 @@ export interface components {
|
|
|
1053
1205
|
};
|
|
1054
1206
|
/** @description Milliseconds until a per-target slot frees */
|
|
1055
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
|
+
};
|
|
1056
1226
|
};
|
|
1057
1227
|
JourneyRunDetail: {
|
|
1058
1228
|
/** @description Run id - the handle for GET /api/journey/runs/{id} and the stream */
|
|
@@ -1084,6 +1254,23 @@ export interface components {
|
|
|
1084
1254
|
verdict?: "satisfied" | "partial" | "unsatisfied" | "not_gradable";
|
|
1085
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. */
|
|
1086
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
|
+
};
|
|
1087
1274
|
/** @description Journey/audit contract version (shared SemVer; see docs) */
|
|
1088
1275
|
contractVersion: string;
|
|
1089
1276
|
/** @description The full run result. Present iff status is 'succeeded'. */
|
|
@@ -1340,6 +1527,41 @@ export interface components {
|
|
|
1340
1527
|
journey_layers?: ("discovery" | "identity" | "access" | "payments" | "experience")[];
|
|
1341
1528
|
};
|
|
1342
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;
|
|
1343
1565
|
};
|
|
1344
1566
|
JourneyDomainRun: {
|
|
1345
1567
|
/** @description Run id - the handle for GET /api/journey/runs/{id} and the stream */
|
|
@@ -1371,6 +1593,23 @@ export interface components {
|
|
|
1371
1593
|
verdict?: "satisfied" | "partial" | "unsatisfied" | "not_gradable";
|
|
1372
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. */
|
|
1373
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
|
+
};
|
|
1374
1613
|
/** @description Journey/audit contract version (shared SemVer; see docs) */
|
|
1375
1614
|
contractVersion: string;
|
|
1376
1615
|
/** @description The full run result. Present iff status is 'succeeded'. */
|
|
@@ -1664,6 +1903,23 @@ export interface components {
|
|
|
1664
1903
|
verdict?: "satisfied" | "partial" | "unsatisfied" | "not_gradable";
|
|
1665
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. */
|
|
1666
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
|
+
};
|
|
1667
1923
|
/** @description Journey/audit contract version (shared SemVer; see docs) */
|
|
1668
1924
|
contractVersion: string;
|
|
1669
1925
|
/** @description The graph-view run result. Present iff status is 'succeeded'. */
|
|
@@ -2066,8 +2322,96 @@ export interface components {
|
|
|
2066
2322
|
/** @description text steps only: the narrative the agent emitted between actions. Advisory - raw model prose. */
|
|
2067
2323
|
text?: string;
|
|
2068
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
|
+
};
|
|
2069
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). */
|
|
2070
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;
|
|
2071
2415
|
/** @description The scanned domain (pre-redirect). Compare with new URL(finalUrl).hostname to detect cross-domain redirects. */
|
|
2072
2416
|
domain?: string;
|
|
2073
2417
|
/** @description The normalized URL */
|
|
@@ -2171,6 +2515,11 @@ export interface components {
|
|
|
2171
2515
|
tier?: "required" | "recommended" | "emerging";
|
|
2172
2516
|
/** @description Optional. Why the check does not apply to this product. Present on 'na' rows; the check is skipped, not deducted. */
|
|
2173
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";
|
|
2174
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. */
|
|
2175
2524
|
estScoreGain?: number;
|
|
2176
2525
|
};
|
|
@@ -2292,10 +2641,17 @@ export interface components {
|
|
|
2292
2641
|
next?: string;
|
|
2293
2642
|
};
|
|
2294
2643
|
/**
|
|
2295
|
-
* @description A partner key's usage per kind, returned by GET /api/usage. Each kind holds one entry per period
|
|
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.
|
|
2296
2645
|
* @example {
|
|
2297
2646
|
* "key": "acme",
|
|
2298
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
|
+
* },
|
|
2299
2655
|
* "month": {
|
|
2300
2656
|
* "used": 1250,
|
|
2301
2657
|
* "limit": 5000,
|
|
@@ -2305,6 +2661,13 @@ export interface components {
|
|
|
2305
2661
|
* }
|
|
2306
2662
|
* },
|
|
2307
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
|
+
* },
|
|
2308
2671
|
* "month": {
|
|
2309
2672
|
* "used": 12,
|
|
2310
2673
|
* "limit": null,
|
|
@@ -2320,10 +2683,12 @@ export interface components {
|
|
|
2320
2683
|
key: string;
|
|
2321
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. */
|
|
2322
2685
|
scans: {
|
|
2686
|
+
day: components["schemas"]["KeyUsagePeriod"];
|
|
2323
2687
|
month: components["schemas"]["KeyUsagePeriod"];
|
|
2324
2688
|
};
|
|
2325
2689
|
/** @description Journey dispatches: POST /api/journey/runs and POST /api/journey/domains/{host}. */
|
|
2326
2690
|
journeys: {
|
|
2691
|
+
day: components["schemas"]["KeyUsagePeriod"];
|
|
2327
2692
|
month: components["schemas"]["KeyUsagePeriod"];
|
|
2328
2693
|
};
|
|
2329
2694
|
};
|
|
@@ -2337,12 +2702,12 @@ export interface components {
|
|
|
2337
2702
|
remaining: number | null;
|
|
2338
2703
|
/**
|
|
2339
2704
|
* Format: date-time
|
|
2340
|
-
* @description Start of the current period
|
|
2705
|
+
* @description Start of the current period: 00:00 UTC today for day, the 1st of the month at 00:00 UTC for month.
|
|
2341
2706
|
*/
|
|
2342
2707
|
period_start: string;
|
|
2343
2708
|
/**
|
|
2344
2709
|
* Format: date-time
|
|
2345
|
-
* @description When the count resets
|
|
2710
|
+
* @description When the count resets: 00:00 UTC tomorrow for day, the 1st of next month at 00:00 UTC for month.
|
|
2346
2711
|
*/
|
|
2347
2712
|
resets_at: string;
|
|
2348
2713
|
};
|
|
@@ -2647,6 +3012,8 @@ export interface operations {
|
|
|
2647
3012
|
siteType?: "content" | "business" | "app" | "store";
|
|
2648
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. */
|
|
2649
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;
|
|
2650
3017
|
};
|
|
2651
3018
|
};
|
|
2652
3019
|
};
|
|
@@ -2669,7 +3036,7 @@ export interface operations {
|
|
|
2669
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. */
|
|
2670
3037
|
202: {
|
|
2671
3038
|
headers: {
|
|
2672
|
-
/** @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. */
|
|
2673
3040
|
Location?: string;
|
|
2674
3041
|
};
|
|
2675
3042
|
content: {
|
|
@@ -2691,7 +3058,7 @@ export interface operations {
|
|
|
2691
3058
|
"application/json": components["schemas"]["McpAuthRequiredResponse"];
|
|
2692
3059
|
};
|
|
2693
3060
|
};
|
|
2694
|
-
/** @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 monthly scan limit gets 429 with error `usage_limit_reached` and `kind`, `period
|
|
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. */
|
|
2695
3062
|
429: {
|
|
2696
3063
|
headers: {
|
|
2697
3064
|
/** @description Seconds until next allowed request */
|
|
@@ -2769,7 +3136,7 @@ export interface operations {
|
|
|
2769
3136
|
"application/json": components["schemas"]["ErrorResponse"];
|
|
2770
3137
|
};
|
|
2771
3138
|
};
|
|
2772
|
-
/** @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 monthly scan limit gets 429 with error `usage_limit_reached` and `kind`, `period
|
|
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. */
|
|
2773
3140
|
429: {
|
|
2774
3141
|
headers: {
|
|
2775
3142
|
/** @description Seconds until next allowed request */
|
|
@@ -2810,6 +3177,8 @@ export interface operations {
|
|
|
2810
3177
|
ephemeral?: "1";
|
|
2811
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. */
|
|
2812
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;
|
|
2813
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. */
|
|
2814
3183
|
format?: "audit";
|
|
2815
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. */
|
|
@@ -2819,7 +3188,7 @@ export interface operations {
|
|
|
2819
3188
|
};
|
|
2820
3189
|
};
|
|
2821
3190
|
responses: {
|
|
2822
|
-
/** @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. */
|
|
2823
3192
|
200: {
|
|
2824
3193
|
content: {
|
|
2825
3194
|
"text/event-stream": string;
|
|
@@ -2829,7 +3198,7 @@ export interface operations {
|
|
|
2829
3198
|
400: {
|
|
2830
3199
|
content: never;
|
|
2831
3200
|
};
|
|
2832
|
-
/** @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 monthly scan limit gets 429 with error `usage_limit_reached` and `kind`, `period
|
|
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. */
|
|
2833
3202
|
429: {
|
|
2834
3203
|
headers: {
|
|
2835
3204
|
/** @description Seconds until next allowed request */
|
|
@@ -2862,7 +3231,7 @@ export interface operations {
|
|
|
2862
3231
|
"application/json": components["schemas"]["ErrorResponse"];
|
|
2863
3232
|
};
|
|
2864
3233
|
};
|
|
2865
|
-
/** @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 monthly scan limit gets 429 with error `usage_limit_reached` and `kind`, `period
|
|
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. */
|
|
2866
3235
|
429: {
|
|
2867
3236
|
headers: {
|
|
2868
3237
|
/** @description Seconds until next allowed request */
|
|
@@ -2885,6 +3254,10 @@ export interface operations {
|
|
|
2885
3254
|
getScore: {
|
|
2886
3255
|
parameters: {
|
|
2887
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;
|
|
2888
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. */
|
|
2889
3262
|
competitors?: "1";
|
|
2890
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. */
|
|
@@ -2895,7 +3268,7 @@ export interface operations {
|
|
|
2895
3268
|
siteType?: "content" | "business" | "app" | "store";
|
|
2896
3269
|
};
|
|
2897
3270
|
path: {
|
|
2898
|
-
/** @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. */
|
|
2899
3272
|
domain: string;
|
|
2900
3273
|
};
|
|
2901
3274
|
};
|
|
@@ -2916,10 +3289,14 @@ export interface operations {
|
|
|
2916
3289
|
};
|
|
2917
3290
|
};
|
|
2918
3291
|
};
|
|
2919
|
-
/** @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`). */
|
|
2920
3297
|
404: {
|
|
2921
3298
|
content: {
|
|
2922
|
-
"application/json": components["schemas"]["NotScannedResponse"];
|
|
3299
|
+
"application/json": components["schemas"]["NotScannedResponse"] | components["schemas"]["ErrorResponse"];
|
|
2923
3300
|
};
|
|
2924
3301
|
};
|
|
2925
3302
|
/** @description MCP authentication is required. No score or grade was produced. The failed attempt does not overwrite a previous measured scan. */
|
|
@@ -2942,6 +3319,45 @@ export interface operations {
|
|
|
2942
3319
|
500: {
|
|
2943
3320
|
content: never;
|
|
2944
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
|
+
};
|
|
2945
3361
|
};
|
|
2946
3362
|
};
|
|
2947
3363
|
/**
|
|
@@ -2968,15 +3384,57 @@ export interface operations {
|
|
|
2968
3384
|
};
|
|
2969
3385
|
};
|
|
2970
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
|
+
};
|
|
2971
3427
|
/**
|
|
2972
3428
|
* Get the complete catalog of scanner checks
|
|
2973
|
-
* @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.
|
|
2974
3430
|
*/
|
|
2975
3431
|
listChecks: {
|
|
2976
3432
|
parameters: {
|
|
2977
3433
|
query?: {
|
|
2978
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). */
|
|
2979
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;
|
|
2980
3438
|
};
|
|
2981
3439
|
};
|
|
2982
3440
|
responses: {
|
|
@@ -3389,7 +3847,7 @@ export interface operations {
|
|
|
3389
3847
|
};
|
|
3390
3848
|
/**
|
|
3391
3849
|
* Draft a domain's own agent discovery files (ard.json, ai-catalog.json, poppy.json)
|
|
3392
|
-
* @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>`.
|
|
3393
3851
|
*/
|
|
3394
3852
|
generateAgentFiles: {
|
|
3395
3853
|
parameters: {
|
|
@@ -3510,7 +3968,7 @@ export interface operations {
|
|
|
3510
3968
|
};
|
|
3511
3969
|
};
|
|
3512
3970
|
responses: {
|
|
3513
|
-
/** @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. */
|
|
3514
3972
|
200: {
|
|
3515
3973
|
headers: {
|
|
3516
3974
|
/** @description Seconds until the target's oldest in-window run ages out */
|
|
@@ -3526,7 +3984,7 @@ export interface operations {
|
|
|
3526
3984
|
"application/json": components["schemas"]["JourneyCappedRun"];
|
|
3527
3985
|
};
|
|
3528
3986
|
};
|
|
3529
|
-
/** @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. */
|
|
3530
3988
|
201: {
|
|
3531
3989
|
headers: {
|
|
3532
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 */
|
|
@@ -3540,39 +3998,51 @@ export interface operations {
|
|
|
3540
3998
|
"application/json": components["schemas"]["JourneyCreatedRun"];
|
|
3541
3999
|
};
|
|
3542
4000
|
};
|
|
3543
|
-
/** @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. */
|
|
3544
4002
|
400: {
|
|
3545
4003
|
content: {
|
|
3546
|
-
"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
|
+
};
|
|
3547
4008
|
};
|
|
3548
4009
|
};
|
|
3549
|
-
/** @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. */
|
|
3550
4011
|
401: {
|
|
3551
4012
|
content: {
|
|
3552
|
-
"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
|
+
};
|
|
3553
4017
|
};
|
|
3554
4018
|
};
|
|
3555
|
-
/** @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 monthly journey limit gets 429 with error `usage_limit_reached` and `kind`, `period
|
|
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. */
|
|
3556
4020
|
429: {
|
|
3557
4021
|
headers: {
|
|
3558
4022
|
/** @description Seconds until next allowed request */
|
|
3559
4023
|
"Retry-After"?: number;
|
|
3560
4024
|
};
|
|
3561
4025
|
content: {
|
|
3562
|
-
"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
|
+
};
|
|
3563
4030
|
};
|
|
3564
4031
|
};
|
|
3565
|
-
/** @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). */
|
|
3566
4033
|
503: {
|
|
3567
4034
|
content: {
|
|
3568
|
-
"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
|
+
};
|
|
3569
4039
|
};
|
|
3570
4040
|
};
|
|
3571
4041
|
};
|
|
3572
4042
|
};
|
|
3573
4043
|
/**
|
|
3574
4044
|
* Get a journey run record (non-streaming)
|
|
3575
|
-
* @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.
|
|
3576
4046
|
*/
|
|
3577
4047
|
getJourneyRun: {
|
|
3578
4048
|
parameters: {
|
|
@@ -3582,7 +4052,7 @@ export interface operations {
|
|
|
3582
4052
|
};
|
|
3583
4053
|
};
|
|
3584
4054
|
responses: {
|
|
3585
|
-
/** @description The run record; plus `result` once succeeded. */
|
|
4055
|
+
/** @description The run record; plus `result` and `flags` once succeeded, and `next_action` until then. */
|
|
3586
4056
|
200: {
|
|
3587
4057
|
content: {
|
|
3588
4058
|
"application/json": components["schemas"]["JourneyRunDetail"];
|
|
@@ -3596,7 +4066,7 @@ export interface operations {
|
|
|
3596
4066
|
};
|
|
3597
4067
|
/**
|
|
3598
4068
|
* Get or create a domain's agent journey
|
|
3599
|
-
* @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 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.
|
|
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.
|
|
3600
4070
|
*/
|
|
3601
4071
|
getOrCreateDomainJourney: {
|
|
3602
4072
|
parameters: {
|
|
@@ -3610,7 +4080,7 @@ export interface operations {
|
|
|
3610
4080
|
};
|
|
3611
4081
|
};
|
|
3612
4082
|
responses: {
|
|
3613
|
-
/** @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). */
|
|
3614
4084
|
200: {
|
|
3615
4085
|
content: {
|
|
3616
4086
|
"application/json": components["schemas"]["JourneyDomainRun"] | components["schemas"]["JourneyDomainRunGraph"];
|
|
@@ -3634,7 +4104,7 @@ export interface operations {
|
|
|
3634
4104
|
"application/json": components["schemas"]["ErrorResponse"];
|
|
3635
4105
|
};
|
|
3636
4106
|
};
|
|
3637
|
-
/** @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 monthly journey limit, with `kind`, `period
|
|
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. */
|
|
3638
4108
|
429: {
|
|
3639
4109
|
headers: {
|
|
3640
4110
|
/** @description Seconds until next allowed request */
|
|
@@ -3746,7 +4216,7 @@ export interface operations {
|
|
|
3746
4216
|
};
|
|
3747
4217
|
/**
|
|
3748
4218
|
* Read your partner API key's usage and usage limits
|
|
3749
|
-
* @description Returns the calling key's own usage for the current period, per kind (scans, journeys) and per period (
|
|
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.
|
|
3750
4220
|
*/
|
|
3751
4221
|
getKeyUsage: {
|
|
3752
4222
|
responses: {
|