ax 0.10.1 → 0.10.3
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/dist/api/shared.d.ts +9 -0
- package/dist/contract/types.gen.d.ts +346 -26
- package/dist/contract/version.d.ts +1 -1
- package/dist/index.cjs +19 -1
- package/dist/index.js +19 -1
- package/dist/main.cjs +60 -60
- package/package.json +3 -3
package/dist/api/shared.d.ts
CHANGED
|
@@ -22,6 +22,15 @@ export declare function errorBody(res: Response): Promise<{
|
|
|
22
22
|
code: string | null;
|
|
23
23
|
payload: unknown;
|
|
24
24
|
}>;
|
|
25
|
+
/**
|
|
26
|
+
* The key-wide 429 a partner key gets once it has used its monthly usage
|
|
27
|
+
* limit (contract 1.37.0): `error: "usage_limit_reached"` with `kind`,
|
|
28
|
+
* `period`, `used`, `limit` and `resets_at`. Its Retry-After counts to the
|
|
29
|
+
* next 1st of the month, so it must not be read as the per-minute or daily
|
|
30
|
+
* limits the other 429s describe. Returns the message to show, or null for
|
|
31
|
+
* any other 429. Reads a clone, so the caller can still consume the body.
|
|
32
|
+
*/
|
|
33
|
+
export declare function usageLimitMessage(res: Response): Promise<string | null>;
|
|
25
34
|
/** Best-effort human message from an error response body. */
|
|
26
35
|
export declare function errorBodyText(res: Response): Promise<string>;
|
|
27
36
|
export declare const pause: (ms: number) => Promise<void>;
|
|
@@ -9,6 +9,18 @@ type Without<T, U> = {
|
|
|
9
9
|
type XOR<T, U> = (T | U) extends object ? (Without<T, U> & U) | (Without<U, T> & T) : T | U;
|
|
10
10
|
type OneOf<T extends any[]> = T extends [infer Only] ? Only : T extends [infer A, infer B, ...infer Rest] ? OneOf<[XOR<A, B>, ...Rest]> : never;
|
|
11
11
|
export interface paths {
|
|
12
|
+
"/ask": {
|
|
13
|
+
/**
|
|
14
|
+
* Retrieve published website evidence
|
|
15
|
+
* @description Ora GET convenience adapter for NLWeb list retrieval. Use POST for the canonical envelope and context. JSON is the default.
|
|
16
|
+
*/
|
|
17
|
+
get: operations["askPublishedWebsiteGet"];
|
|
18
|
+
/**
|
|
19
|
+
* Retrieve published website evidence
|
|
20
|
+
* @description NLWeb v0.55 synchronous list/conversational_search profile. JSON by default; prefer.streaming, or an Accept header preferring text/event-stream when prefer.streaming is absent, selects named SSE events. Unsupported modes/formats return HTTP 200 failure envelopes. No promises or await.
|
|
21
|
+
*/
|
|
22
|
+
post: operations["askPublishedWebsitePost"];
|
|
23
|
+
};
|
|
12
24
|
"/api/scan": {
|
|
13
25
|
/**
|
|
14
26
|
* Scan a domain, MCP server URL, or MCP App URL for agent-readiness
|
|
@@ -82,14 +94,14 @@ export interface paths {
|
|
|
82
94
|
"/api/ard/search": {
|
|
83
95
|
/**
|
|
84
96
|
* Search agentic resources (Agentic Resource Discovery)
|
|
85
|
-
* @description Runs an Agentic Resource Discovery (ARD) search over ora's catalog of agent-ready resources. Returns resources ranked by relevance to a free-text query, with optional field filters and federation control. The per-result `score` is
|
|
97
|
+
* @description Runs an Agentic Resource Discovery (ARD) search over ora's catalog of agent-ready resources. Returns resources ranked by relevance to a free-text query, with optional field filters and federation control. The per-result `score` is pure relevance (0-100): match quality for the query, never a trust or readiness rating. Results are ordered by relevance with agent-readiness reordering close matches, so `score` need not decrease down the list; the readiness itself is in `oraScorecard` and GET /api/score/{domain}. Rate limited to 30 requests per minute per IP - returns 429 if exceeded.
|
|
86
98
|
*/
|
|
87
99
|
post: operations["ardSearch"];
|
|
88
100
|
};
|
|
89
101
|
"/api/ard/explore": {
|
|
90
102
|
/**
|
|
91
103
|
* Faceted exploration of agentic resources (Agentic Resource Discovery)
|
|
92
|
-
* @description Returns facet aggregations (counts per field value) for an Agentic Resource Discovery (ARD) result set. Use this to build filter UIs over the ARD catalog. An optional query narrows the set before faceting. Rate limited to 30 requests per minute per IP - returns 429 if exceeded.
|
|
104
|
+
* @description Returns facet aggregations (counts per field value) for an Agentic Resource Discovery (ARD) result set. Use this to build filter UIs over the ARD catalog. A `type` bucket's value is the raw media type, so it can be used as a filter value as-is. An optional query narrows the set before faceting: with text, the set is exactly what POST /api/ard/search matches for the same text and filter; without it, the whole index narrowed by the filter. Rate limited to 30 requests per minute per IP - returns 429 if exceeded.
|
|
93
105
|
*/
|
|
94
106
|
post: operations["ardExplore"];
|
|
95
107
|
};
|
|
@@ -131,7 +143,7 @@ export interface paths {
|
|
|
131
143
|
"/api/agent-files/{domain}": {
|
|
132
144
|
/**
|
|
133
145
|
* Draft a domain's own agent discovery files (ard.json, ai-catalog.json, poppy.json)
|
|
134
|
-
* @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, Draft 0.
|
|
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, Draft 0.2). 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>`.
|
|
135
147
|
*/
|
|
136
148
|
get: operations["generateAgentFiles"];
|
|
137
149
|
};
|
|
@@ -166,7 +178,7 @@ export interface paths {
|
|
|
166
178
|
"/api/journey/domains/{host}": {
|
|
167
179
|
/**
|
|
168
180
|
* Get or create a domain's agent journey
|
|
169
|
-
* @description Returns the agent journey for a domain, running one only if there is not one already. Send only the domain and no body: ora selects the intent and the agent. Requires an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora); without one, 401 PARTNER_KEY_REQUIRED. 200 means nothing was dispatched and an existing run answered, either finished (carrying its `result`) or still running (open `stream_url` to watch it). 201 means a new run was dispatched. Branch on `dispatched`. Two response views (see the `view` parameter): `graph` (JourneyDomainRunGraph, the default - `result` narrowed to what drawing the journey needs) and `full` (JourneyDomainRun, the complete projection, on `?view=full`). A finished run is served indefinitely; `run_age_seconds` gives its age. There is no per-caller rate limit on this endpoint. Each domain is capped at 100 runs per rolling 24h, and one domain cannot start two runs at once - both are per-domain, neither limits how many domains you may ask for or how fast.
|
|
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.
|
|
170
182
|
*/
|
|
171
183
|
post: operations["getOrCreateDomainJourney"];
|
|
172
184
|
};
|
|
@@ -191,6 +203,13 @@ export interface paths {
|
|
|
191
203
|
*/
|
|
192
204
|
get: operations["listJourneyAgents"];
|
|
193
205
|
};
|
|
206
|
+
"/api/usage": {
|
|
207
|
+
/**
|
|
208
|
+
* 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 (only month today, 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
|
+
*/
|
|
211
|
+
get: operations["getKeyUsage"];
|
|
212
|
+
};
|
|
194
213
|
"/api/feedback/{domain}": {
|
|
195
214
|
/**
|
|
196
215
|
* Get agent feedback for a product
|
|
@@ -202,6 +221,102 @@ export interface paths {
|
|
|
202
221
|
export type webhooks = Record<string, never>;
|
|
203
222
|
export interface components {
|
|
204
223
|
schemas: {
|
|
224
|
+
NlwebAskRequest: {
|
|
225
|
+
query: {
|
|
226
|
+
text: string;
|
|
227
|
+
site?: string;
|
|
228
|
+
[key: string]: unknown;
|
|
229
|
+
};
|
|
230
|
+
context?: {
|
|
231
|
+
"@type"?: string;
|
|
232
|
+
prev?: string[];
|
|
233
|
+
text?: string;
|
|
234
|
+
memory?: string;
|
|
235
|
+
[key: string]: unknown;
|
|
236
|
+
};
|
|
237
|
+
prefer?: {
|
|
238
|
+
streaming?: boolean;
|
|
239
|
+
response_format?: string;
|
|
240
|
+
mode?: string;
|
|
241
|
+
"accept-language"?: string;
|
|
242
|
+
"user-agent"?: string;
|
|
243
|
+
limit?: number;
|
|
244
|
+
[key: string]: unknown;
|
|
245
|
+
};
|
|
246
|
+
meta?: {
|
|
247
|
+
version?: string;
|
|
248
|
+
session_context?: {
|
|
249
|
+
[key: string]: unknown;
|
|
250
|
+
};
|
|
251
|
+
user?: string | {
|
|
252
|
+
[key: string]: unknown;
|
|
253
|
+
};
|
|
254
|
+
remember?: boolean;
|
|
255
|
+
request_id?: string;
|
|
256
|
+
[key: string]: unknown;
|
|
257
|
+
};
|
|
258
|
+
[key: string]: unknown;
|
|
259
|
+
};
|
|
260
|
+
NlwebAskResponse: ({
|
|
261
|
+
_meta: {
|
|
262
|
+
/** @constant */
|
|
263
|
+
version: "0.55";
|
|
264
|
+
request_id?: string;
|
|
265
|
+
/** @constant */
|
|
266
|
+
response_type: "answer";
|
|
267
|
+
/** @constant */
|
|
268
|
+
response_format: "conversational_search";
|
|
269
|
+
release: {
|
|
270
|
+
id: string;
|
|
271
|
+
};
|
|
272
|
+
[key: string]: unknown;
|
|
273
|
+
};
|
|
274
|
+
results: ({
|
|
275
|
+
/** @constant */
|
|
276
|
+
"@type": "WebPage";
|
|
277
|
+
/** Format: uri */
|
|
278
|
+
url: string;
|
|
279
|
+
name: string;
|
|
280
|
+
site: string;
|
|
281
|
+
score: number;
|
|
282
|
+
description: string;
|
|
283
|
+
grounding: {
|
|
284
|
+
evidence: ({
|
|
285
|
+
id: string;
|
|
286
|
+
documentId: string;
|
|
287
|
+
/** Format: uri */
|
|
288
|
+
url: string;
|
|
289
|
+
text: string;
|
|
290
|
+
start: number;
|
|
291
|
+
end: number;
|
|
292
|
+
/** @enum {string} */
|
|
293
|
+
view: "origin" | "published";
|
|
294
|
+
context?: {
|
|
295
|
+
/** @constant */
|
|
296
|
+
profile: "adjacent-passages-v1";
|
|
297
|
+
anchorStart: number;
|
|
298
|
+
anchorEnd: number;
|
|
299
|
+
passageIds: string[];
|
|
300
|
+
};
|
|
301
|
+
})[];
|
|
302
|
+
};
|
|
303
|
+
})[];
|
|
304
|
+
}) | {
|
|
305
|
+
_meta: {
|
|
306
|
+
/** @constant */
|
|
307
|
+
version: "0.55";
|
|
308
|
+
request_id?: string;
|
|
309
|
+
/** @constant */
|
|
310
|
+
response_type: "failure";
|
|
311
|
+
[key: string]: unknown;
|
|
312
|
+
};
|
|
313
|
+
error: {
|
|
314
|
+
code: string;
|
|
315
|
+
message: string;
|
|
316
|
+
status?: number;
|
|
317
|
+
retry_after?: number;
|
|
318
|
+
};
|
|
319
|
+
};
|
|
205
320
|
AuditCheck: {
|
|
206
321
|
/** @description Stable check identifier (e.g. 'api-error-model'). Route fixes and dedupe by this - names are for display, ids are stable. */
|
|
207
322
|
id: string;
|
|
@@ -431,7 +546,7 @@ export interface components {
|
|
|
431
546
|
* @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.
|
|
432
547
|
* @enum {string}
|
|
433
548
|
*/
|
|
434
|
-
contractVersion: "1.
|
|
549
|
+
contractVersion: "1.38.0";
|
|
435
550
|
/**
|
|
436
551
|
* @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.
|
|
437
552
|
* @enum {boolean}
|
|
@@ -634,7 +749,7 @@ export interface components {
|
|
|
634
749
|
* @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.
|
|
635
750
|
* @enum {string}
|
|
636
751
|
*/
|
|
637
|
-
contractVersion: "1.
|
|
752
|
+
contractVersion: "1.38.0";
|
|
638
753
|
/** @description Wall-clock duration of the scan that produced this stored result */
|
|
639
754
|
durationMs: number | null;
|
|
640
755
|
/**
|
|
@@ -682,7 +797,7 @@ export interface components {
|
|
|
682
797
|
* @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.
|
|
683
798
|
* @enum {string}
|
|
684
799
|
*/
|
|
685
|
-
contractVersion: "1.
|
|
800
|
+
contractVersion: "1.38.0";
|
|
686
801
|
/** @description The four scored layers in scoring order, with display name and current weight. */
|
|
687
802
|
layers: {
|
|
688
803
|
/** @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'. */
|
|
@@ -781,7 +896,7 @@ export interface components {
|
|
|
781
896
|
* @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.
|
|
782
897
|
* @enum {string}
|
|
783
898
|
*/
|
|
784
|
-
contractVersion: "1.
|
|
899
|
+
contractVersion: "1.38.0";
|
|
785
900
|
/** @description The apex domain derived from the requested URL. */
|
|
786
901
|
domain: string;
|
|
787
902
|
/** @description The normalized URL the run targeted. */
|
|
@@ -2176,6 +2291,61 @@ export interface components {
|
|
|
2176
2291
|
/** @description Optional recovery hint (e.g. /api/scan on NOT_FOUND). */
|
|
2177
2292
|
next?: string;
|
|
2178
2293
|
};
|
|
2294
|
+
/**
|
|
2295
|
+
* @description A partner key's usage per kind, returned by GET /api/usage. Each kind holds one entry per period; month is the only period today, and a future period is a sibling key next to it.
|
|
2296
|
+
* @example {
|
|
2297
|
+
* "key": "acme",
|
|
2298
|
+
* "scans": {
|
|
2299
|
+
* "month": {
|
|
2300
|
+
* "used": 1250,
|
|
2301
|
+
* "limit": 5000,
|
|
2302
|
+
* "remaining": 3750,
|
|
2303
|
+
* "period_start": "2026-10-01T00:00:00.000Z",
|
|
2304
|
+
* "resets_at": "2026-11-01T00:00:00.000Z"
|
|
2305
|
+
* }
|
|
2306
|
+
* },
|
|
2307
|
+
* "journeys": {
|
|
2308
|
+
* "month": {
|
|
2309
|
+
* "used": 12,
|
|
2310
|
+
* "limit": null,
|
|
2311
|
+
* "remaining": null,
|
|
2312
|
+
* "period_start": "2026-10-01T00:00:00.000Z",
|
|
2313
|
+
* "resets_at": "2026-11-01T00:00:00.000Z"
|
|
2314
|
+
* }
|
|
2315
|
+
* }
|
|
2316
|
+
* }
|
|
2317
|
+
*/
|
|
2318
|
+
KeyUsage: {
|
|
2319
|
+
/** @description The name of the key that made the request. */
|
|
2320
|
+
key: string;
|
|
2321
|
+
/** @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
|
+
scans: {
|
|
2323
|
+
month: components["schemas"]["KeyUsagePeriod"];
|
|
2324
|
+
};
|
|
2325
|
+
/** @description Journey dispatches: POST /api/journey/runs and POST /api/journey/domains/{host}. */
|
|
2326
|
+
journeys: {
|
|
2327
|
+
month: components["schemas"]["KeyUsagePeriod"];
|
|
2328
|
+
};
|
|
2329
|
+
};
|
|
2330
|
+
/** @description One kind's usage in one period. */
|
|
2331
|
+
KeyUsagePeriod: {
|
|
2332
|
+
/** @description New dispatches the key started since period_start. */
|
|
2333
|
+
used: number;
|
|
2334
|
+
/** @description The key's limit for this kind and period; null when it has none. */
|
|
2335
|
+
limit: number | null;
|
|
2336
|
+
/** @description limit minus used, never below 0; null when there is no limit. At 0 the endpoints that dispatch this kind answer 429 usage_limit_reached until resets_at. */
|
|
2337
|
+
remaining: number | null;
|
|
2338
|
+
/**
|
|
2339
|
+
* Format: date-time
|
|
2340
|
+
* @description Start of the current period (the 1st of the month, 00:00 UTC).
|
|
2341
|
+
*/
|
|
2342
|
+
period_start: string;
|
|
2343
|
+
/**
|
|
2344
|
+
* Format: date-time
|
|
2345
|
+
* @description When the count resets (the 1st of next month, 00:00 UTC).
|
|
2346
|
+
*/
|
|
2347
|
+
resets_at: string;
|
|
2348
|
+
};
|
|
2179
2349
|
/** @description Draft agent discovery files for one domain, returned by GET /api/agent-files/{domain}. */
|
|
2180
2350
|
AgentFilesBundle: {
|
|
2181
2351
|
/** @description The domain the files speak for (leading www. dropped). */
|
|
@@ -2324,6 +2494,115 @@ export interface components {
|
|
|
2324
2494
|
export type $defs = Record<string, never>;
|
|
2325
2495
|
export type external = Record<string, never>;
|
|
2326
2496
|
export interface operations {
|
|
2497
|
+
/**
|
|
2498
|
+
* Retrieve published website evidence
|
|
2499
|
+
* @description Ora GET convenience adapter for NLWeb list retrieval. Use POST for the canonical envelope and context. JSON is the default.
|
|
2500
|
+
*/
|
|
2501
|
+
askPublishedWebsiteGet: {
|
|
2502
|
+
parameters: {
|
|
2503
|
+
query: {
|
|
2504
|
+
query: string;
|
|
2505
|
+
site?: string;
|
|
2506
|
+
mode?: string;
|
|
2507
|
+
streaming?: boolean;
|
|
2508
|
+
limit?: number;
|
|
2509
|
+
query_id?: string;
|
|
2510
|
+
};
|
|
2511
|
+
};
|
|
2512
|
+
responses: {
|
|
2513
|
+
/** @description NLWeb answer with retrieved evidence and source provenance, or application failure. */
|
|
2514
|
+
200: {
|
|
2515
|
+
content: {
|
|
2516
|
+
"application/json": components["schemas"]["NlwebAskResponse"];
|
|
2517
|
+
"text/event-stream": string;
|
|
2518
|
+
};
|
|
2519
|
+
};
|
|
2520
|
+
/** @description Malformed NLWeb request. */
|
|
2521
|
+
400: {
|
|
2522
|
+
content: never;
|
|
2523
|
+
};
|
|
2524
|
+
/** @description Request Origin is not this website. */
|
|
2525
|
+
403: {
|
|
2526
|
+
content: never;
|
|
2527
|
+
};
|
|
2528
|
+
/** @description Domain querying is disabled or no eligible publication exists. */
|
|
2529
|
+
404: {
|
|
2530
|
+
content: never;
|
|
2531
|
+
};
|
|
2532
|
+
/** @description Accept does not allow the requested response transport. */
|
|
2533
|
+
406: {
|
|
2534
|
+
content: never;
|
|
2535
|
+
};
|
|
2536
|
+
/** @description Shared query allowance exhausted. */
|
|
2537
|
+
429: {
|
|
2538
|
+
headers: {
|
|
2539
|
+
/** @description Seconds until retry. */
|
|
2540
|
+
"Retry-After"?: number;
|
|
2541
|
+
};
|
|
2542
|
+
content: never;
|
|
2543
|
+
};
|
|
2544
|
+
/** @description Query service or admission unavailable. */
|
|
2545
|
+
503: {
|
|
2546
|
+
content: never;
|
|
2547
|
+
};
|
|
2548
|
+
/** @description Query deadline exceeded. */
|
|
2549
|
+
504: {
|
|
2550
|
+
content: never;
|
|
2551
|
+
};
|
|
2552
|
+
};
|
|
2553
|
+
};
|
|
2554
|
+
/**
|
|
2555
|
+
* Retrieve published website evidence
|
|
2556
|
+
* @description NLWeb v0.55 synchronous list/conversational_search profile. JSON by default; prefer.streaming, or an Accept header preferring text/event-stream when prefer.streaming is absent, selects named SSE events. Unsupported modes/formats return HTTP 200 failure envelopes. No promises or await.
|
|
2557
|
+
*/
|
|
2558
|
+
askPublishedWebsitePost: {
|
|
2559
|
+
requestBody: {
|
|
2560
|
+
content: {
|
|
2561
|
+
"application/json": components["schemas"]["NlwebAskRequest"];
|
|
2562
|
+
};
|
|
2563
|
+
};
|
|
2564
|
+
responses: {
|
|
2565
|
+
/** @description NLWeb answer with retrieved evidence and source provenance, or application failure. */
|
|
2566
|
+
200: {
|
|
2567
|
+
content: {
|
|
2568
|
+
"application/json": components["schemas"]["NlwebAskResponse"];
|
|
2569
|
+
"text/event-stream": string;
|
|
2570
|
+
};
|
|
2571
|
+
};
|
|
2572
|
+
/** @description Malformed NLWeb request. */
|
|
2573
|
+
400: {
|
|
2574
|
+
content: never;
|
|
2575
|
+
};
|
|
2576
|
+
/** @description Request Origin is not this website. */
|
|
2577
|
+
403: {
|
|
2578
|
+
content: never;
|
|
2579
|
+
};
|
|
2580
|
+
/** @description Domain querying is disabled or no eligible publication exists. */
|
|
2581
|
+
404: {
|
|
2582
|
+
content: never;
|
|
2583
|
+
};
|
|
2584
|
+
/** @description Accept does not allow the requested response transport. */
|
|
2585
|
+
406: {
|
|
2586
|
+
content: never;
|
|
2587
|
+
};
|
|
2588
|
+
/** @description Shared query allowance exhausted. */
|
|
2589
|
+
429: {
|
|
2590
|
+
headers: {
|
|
2591
|
+
/** @description Seconds until retry. */
|
|
2592
|
+
"Retry-After"?: number;
|
|
2593
|
+
};
|
|
2594
|
+
content: never;
|
|
2595
|
+
};
|
|
2596
|
+
/** @description Query service or admission unavailable. */
|
|
2597
|
+
503: {
|
|
2598
|
+
content: never;
|
|
2599
|
+
};
|
|
2600
|
+
/** @description Query deadline exceeded. */
|
|
2601
|
+
504: {
|
|
2602
|
+
content: never;
|
|
2603
|
+
};
|
|
2604
|
+
};
|
|
2605
|
+
};
|
|
2327
2606
|
/**
|
|
2328
2607
|
* Scan a domain, MCP server URL, or MCP App URL for agent-readiness
|
|
2329
2608
|
* @description Runs a full agent-readiness scan on the given URL. Accepts a domain, MCP server URL, or MCP App URL (server that supports the MCP Apps extension `io.modelcontextprotocol/ui`) - the server auto-detects which kind of input was provided and selects the appropriate check set. Catalog-style listing pages are folded into the `mcp` kind by classifying the first validated embedded MCP URL. Returns score, grade, and detailed layer breakdown. The response includes an optional `urlKind` field indicating the detected kind ('domain', 'mcp', or 'mcp-app'). Scoring completes within the request, but deeper analysis can continue asynchronously afterwards: when the returned analysisStatus is 'partial', the response is a 202 Accepted with a Location header pointing at the polling endpoint for the remaining work; a 200 means analysis is already complete. For real-time progress updates, use GET /api/scan/stream which serves a text/event-stream. A complete stored result younger than the freshness window is returned as-is (servedFromCache, resultAgeSeconds, Age header) without running or persisting a scan - pass force: true, or widen/narrow maxAgeSeconds, to control that. Rate limited two ways: 10 requests per minute per IP (burst) and a durable daily scan budget shared with the other scan entry points - both return 429 with a Retry-After header.
|
|
@@ -2412,7 +2691,7 @@ export interface operations {
|
|
|
2412
2691
|
"application/json": components["schemas"]["McpAuthRequiredResponse"];
|
|
2413
2692
|
};
|
|
2414
2693
|
};
|
|
2415
|
-
/** @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. */
|
|
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`, `used`, `limit`, `resets_at` and `retry_after_ms`; its Retry-After counts to the next 1st of the month (UTC). That refusal is key-wide; GET /api/usage shows the numbers. */
|
|
2416
2695
|
429: {
|
|
2417
2696
|
headers: {
|
|
2418
2697
|
/** @description Seconds until next allowed request */
|
|
@@ -2490,7 +2769,7 @@ export interface operations {
|
|
|
2490
2769
|
"application/json": components["schemas"]["ErrorResponse"];
|
|
2491
2770
|
};
|
|
2492
2771
|
};
|
|
2493
|
-
/** @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. */
|
|
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`, `used`, `limit`, `resets_at` and `retry_after_ms`; its Retry-After counts to the next 1st of the month (UTC). That refusal is key-wide; GET /api/usage shows the numbers. */
|
|
2494
2773
|
429: {
|
|
2495
2774
|
headers: {
|
|
2496
2775
|
/** @description Seconds until next allowed request */
|
|
@@ -2550,7 +2829,7 @@ export interface operations {
|
|
|
2550
2829
|
400: {
|
|
2551
2830
|
content: never;
|
|
2552
2831
|
};
|
|
2553
|
-
/** @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. */
|
|
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`, `used`, `limit`, `resets_at` and `retry_after_ms`; its Retry-After counts to the next 1st of the month (UTC). That refusal is key-wide; GET /api/usage shows the numbers. */
|
|
2554
2833
|
429: {
|
|
2555
2834
|
headers: {
|
|
2556
2835
|
/** @description Seconds until next allowed request */
|
|
@@ -2583,7 +2862,7 @@ export interface operations {
|
|
|
2583
2862
|
"application/json": components["schemas"]["ErrorResponse"];
|
|
2584
2863
|
};
|
|
2585
2864
|
};
|
|
2586
|
-
/** @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. */
|
|
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`, `used`, `limit`, `resets_at` and `retry_after_ms`; its Retry-After counts to the next 1st of the month (UTC). That refusal is key-wide; GET /api/usage shows the numbers. */
|
|
2587
2866
|
429: {
|
|
2588
2867
|
headers: {
|
|
2589
2868
|
/** @description Seconds until next allowed request */
|
|
@@ -2864,22 +3143,24 @@ export interface operations {
|
|
|
2864
3143
|
};
|
|
2865
3144
|
/**
|
|
2866
3145
|
* Search agentic resources (Agentic Resource Discovery)
|
|
2867
|
-
* @description Runs an Agentic Resource Discovery (ARD) search over ora's catalog of agent-ready resources. Returns resources ranked by relevance to a free-text query, with optional field filters and federation control. The per-result `score` is
|
|
3146
|
+
* @description Runs an Agentic Resource Discovery (ARD) search over ora's catalog of agent-ready resources. Returns resources ranked by relevance to a free-text query, with optional field filters and federation control. The per-result `score` is pure relevance (0-100): match quality for the query, never a trust or readiness rating. Results are ordered by relevance with agent-readiness reordering close matches, so `score` need not decrease down the list; the readiness itself is in `oraScorecard` and GET /api/score/{domain}. Rate limited to 30 requests per minute per IP - returns 429 if exceeded.
|
|
2868
3147
|
*/
|
|
2869
3148
|
ardSearch: {
|
|
2870
3149
|
requestBody: {
|
|
2871
3150
|
content: {
|
|
2872
3151
|
"application/json": {
|
|
2873
3152
|
query: {
|
|
3153
|
+
/** @description Optional JSON-LD context (a string, object or array, at most 4096 characters serialized). Accepted per ARD v0.91; ora binds no additional filter keys from it. */
|
|
3154
|
+
"@context"?: unknown;
|
|
2874
3155
|
/** @description Free-text search query. May be omitted when filter is present (a filter-only browse); at least one of text/filter is required. */
|
|
2875
3156
|
text?: string;
|
|
2876
|
-
/** @description Optional field filters: a map of field name to an allowed value (a scalar string or an array of strings; OR within a key, AND across keys). */
|
|
3157
|
+
/** @description Optional field filters: a map of field name to an allowed value (a scalar string or an array of strings; OR within a key, AND across keys). Keys: type, identifier, displayName, tags, capabilities, version, publisher (derived from the URN identifier), and literal dot-paths under trustManifest.* and metadata.* (a path crossing an array matches when any element does). Any other key returns 400 INVALID_ARGUMENT. */
|
|
2877
3158
|
filter?: {
|
|
2878
3159
|
[key: string]: string | string[];
|
|
2879
3160
|
};
|
|
2880
3161
|
};
|
|
2881
3162
|
/**
|
|
2882
|
-
* @description Federation policy. 'none': ora's own index only. 'referrals': ora's results plus referrals[] pointers to upstream registries. 'auto': ora merges upstream registry results into results (each tagged with its upstream source); merging is off by default (server-gated) and
|
|
3163
|
+
* @description Federation policy. 'none': ora's own index only. 'referrals': ora's results plus referrals[] pointers to upstream registries. 'auto': ora merges upstream registry results into results (each tagged with its upstream source); merging is off by default (server-gated), and while it is off 'auto' returns referrals[] as 'referrals' does.
|
|
2883
3164
|
* @default auto
|
|
2884
3165
|
* @enum {string}
|
|
2885
3166
|
*/
|
|
@@ -2889,13 +3170,13 @@ export interface operations {
|
|
|
2889
3170
|
* @default 10
|
|
2890
3171
|
*/
|
|
2891
3172
|
pageSize?: number;
|
|
2892
|
-
/** @description Opaque pagination token from a previous response. */
|
|
3173
|
+
/** @description Opaque pagination token from a previous response. A token ora did not issue returns 400 INVALID_ARGUMENT. */
|
|
2893
3174
|
pageToken?: string;
|
|
2894
3175
|
};
|
|
2895
3176
|
};
|
|
2896
3177
|
};
|
|
2897
3178
|
responses: {
|
|
2898
|
-
/** @description The ARD SearchResponse: { results, referrals, pageToken? }. pageToken is omitted when the result set is exhausted (never null).
|
|
3179
|
+
/** @description The ARD SearchResponse: { results, referrals, pageToken? }. pageToken is omitted when the result set is exhausted (never null). referrals lists upstream registries in 'referrals' mode, and in 'auto' mode while upstream merging is off. Each result's trustManifest.attestations[0] is a reference { type, uri, mediaType } to GET /api/ard/attestation/{domain}, not inlined claims. Results from ora's own index also carry an `oraScorecard` vendor extension ({ score?, grade?, category?, checkedAt? }): agent-readiness score/grade only when ora has scored the domain (never a fabricated 0/F), category whenever ora has classified it - all distinct from the relevance `score`; the signed claim remains the attestation endpoint. Ora product entries (type application/vnd.ora.product+json) reference the JSON score document GET /api/score/{domain} as their url when scored, or carry inline data { domain, name, category?, status: 'not_scanned' } when not, with the human report page in `oraReportUrl`; skill entries use application/agent-skills+md (a type filter on the earlier application/ai-skill+md matches too). Entries crawled from other publishers' catalogs carry `oraPublisherBinding`: 'verified' when the entry's urn:air publisher is the site ora crawled it from, else 'unverified' (ARD §4.5.1); an unverified entry carries no trustManifest and sorts after verified ones at equal relevance. */
|
|
2899
3180
|
200: {
|
|
2900
3181
|
content: never;
|
|
2901
3182
|
};
|
|
@@ -2921,7 +3202,7 @@ export interface operations {
|
|
|
2921
3202
|
};
|
|
2922
3203
|
/**
|
|
2923
3204
|
* Faceted exploration of agentic resources (Agentic Resource Discovery)
|
|
2924
|
-
* @description Returns facet aggregations (counts per field value) for an Agentic Resource Discovery (ARD) result set. Use this to build filter UIs over the ARD catalog. An optional query narrows the set before faceting. Rate limited to 30 requests per minute per IP - returns 429 if exceeded.
|
|
3205
|
+
* @description Returns facet aggregations (counts per field value) for an Agentic Resource Discovery (ARD) result set. Use this to build filter UIs over the ARD catalog. A `type` bucket's value is the raw media type, so it can be used as a filter value as-is. An optional query narrows the set before faceting: with text, the set is exactly what POST /api/ard/search matches for the same text and filter; without it, the whole index narrowed by the filter. Rate limited to 30 requests per minute per IP - returns 429 if exceeded.
|
|
2925
3206
|
*/
|
|
2926
3207
|
ardExplore: {
|
|
2927
3208
|
requestBody: {
|
|
@@ -2929,15 +3210,18 @@ export interface operations {
|
|
|
2929
3210
|
"application/json": {
|
|
2930
3211
|
/** @description Optional query to narrow the set before faceting (same shape as POST /api/ard/search's query). */
|
|
2931
3212
|
query?: {
|
|
3213
|
+
/** @description Optional JSON-LD context, as on POST /api/ard/search. */
|
|
3214
|
+
"@context"?: unknown;
|
|
2932
3215
|
/** @description Free-text search query. */
|
|
2933
3216
|
text?: string;
|
|
3217
|
+
/** @description Same keys as POST /api/ard/search's filter; an unsupported key returns 400 INVALID_ARGUMENT. */
|
|
2934
3218
|
filter?: {
|
|
2935
3219
|
[key: string]: string[];
|
|
2936
3220
|
};
|
|
2937
3221
|
};
|
|
2938
3222
|
resultType: {
|
|
2939
3223
|
facets: {
|
|
2940
|
-
/** @description The resource field to aggregate on. */
|
|
3224
|
+
/** @description The resource field to aggregate on: any search filter key, or category. An unsupported field returns 400 INVALID_ARGUMENT. */
|
|
2941
3225
|
field: string;
|
|
2942
3226
|
/** @description Max facet values to return for this field. */
|
|
2943
3227
|
limit?: number;
|
|
@@ -2980,11 +3264,11 @@ export interface operations {
|
|
|
2980
3264
|
ardListAgents: {
|
|
2981
3265
|
parameters: {
|
|
2982
3266
|
query?: {
|
|
2983
|
-
/** @description Results per page (1-100, default 20). */
|
|
3267
|
+
/** @description Results per page (1-100, default 20). A larger value clamps to 100; a non-positive or non-integer value returns 400 INVALID_ARGUMENT. */
|
|
2984
3268
|
pageSize?: number;
|
|
2985
|
-
/** @description Opaque pagination token from a previous response. */
|
|
3269
|
+
/** @description Opaque pagination token from a previous response. A token ora did not issue returns 400 INVALID_ARGUMENT. */
|
|
2986
3270
|
pageToken?: string;
|
|
2987
|
-
/** @description EBNF filter expression, e.g. "type = 'application/mcp-server-card+json' AND updatedAfter > '2026-01-01'". Fields: type, displayName, publisherId, tags, updatedAt. Operators: = != > < >= <=, conditions joined by AND. An unsupported field/operator/syntax returns 400 INVALID_ARGUMENT. */
|
|
3271
|
+
/** @description EBNF filter expression, e.g. "type = 'application/mcp-server-card+json' AND updatedAfter > '2026-01-01'". Fields: type, displayName, publisherId, tags, updatedAt (and updatedAfter / updatedBefore). Operators: = != > < >= <=, conditions joined by AND; a comma-separated type, publisherId or tags value means OR. An unsupported field/operator/syntax (createdAfter included) returns 400 INVALID_ARGUMENT. */
|
|
2988
3272
|
filter?: string;
|
|
2989
3273
|
/** @description Sort expression "<field> [ASC|DESC]", e.g. "displayName DESC". Fields: displayName, updatedAt, identifier, type. */
|
|
2990
3274
|
orderBy?: string;
|
|
@@ -3105,7 +3389,7 @@ export interface operations {
|
|
|
3105
3389
|
};
|
|
3106
3390
|
/**
|
|
3107
3391
|
* Draft a domain's own agent discovery files (ard.json, ai-catalog.json, poppy.json)
|
|
3108
|
-
* @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, Draft 0.
|
|
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, Draft 0.2). 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>`.
|
|
3109
3393
|
*/
|
|
3110
3394
|
generateAgentFiles: {
|
|
3111
3395
|
parameters: {
|
|
@@ -3268,7 +3552,7 @@ export interface operations {
|
|
|
3268
3552
|
"application/json": components["schemas"]["ErrorResponse"];
|
|
3269
3553
|
};
|
|
3270
3554
|
};
|
|
3271
|
-
/** @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. */
|
|
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`, `used`, `limit`, `resets_at` and `retry_after_ms`; its Retry-After counts to the next 1st of the month (UTC). That refusal is key-wide; GET /api/usage shows the numbers. */
|
|
3272
3556
|
429: {
|
|
3273
3557
|
headers: {
|
|
3274
3558
|
/** @description Seconds until next allowed request */
|
|
@@ -3312,7 +3596,7 @@ export interface operations {
|
|
|
3312
3596
|
};
|
|
3313
3597
|
/**
|
|
3314
3598
|
* Get or create a domain's agent journey
|
|
3315
|
-
* @description Returns the agent journey for a domain, running one only if there is not one already. Send only the domain and no body: ora selects the intent and the agent. Requires an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora); without one, 401 PARTNER_KEY_REQUIRED. 200 means nothing was dispatched and an existing run answered, either finished (carrying its `result`) or still running (open `stream_url` to watch it). 201 means a new run was dispatched. Branch on `dispatched`. Two response views (see the `view` parameter): `graph` (JourneyDomainRunGraph, the default - `result` narrowed to what drawing the journey needs) and `full` (JourneyDomainRun, the complete projection, on `?view=full`). A finished run is served indefinitely; `run_age_seconds` gives its age. There is no per-caller rate limit on this endpoint. Each domain is capped at 100 runs per rolling 24h, and one domain cannot start two runs at once - both are per-domain, neither limits how many domains you may ask for or how fast.
|
|
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.
|
|
3316
3600
|
*/
|
|
3317
3601
|
getOrCreateDomainJourney: {
|
|
3318
3602
|
parameters: {
|
|
@@ -3350,7 +3634,7 @@ export interface operations {
|
|
|
3350
3634
|
"application/json": components["schemas"]["ErrorResponse"];
|
|
3351
3635
|
};
|
|
3352
3636
|
};
|
|
3353
|
-
/** @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. */
|
|
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`, `used`, `limit`, `resets_at` and `retry_after_ms` in the body and a Retry-After that counts to the next 1st of the month (UTC); stop dispatching journeys until `resets_at`. GET /api/usage shows the numbers. */
|
|
3354
3638
|
429: {
|
|
3355
3639
|
headers: {
|
|
3356
3640
|
/** @description Seconds until next allowed request */
|
|
@@ -3460,6 +3744,42 @@ export interface operations {
|
|
|
3460
3744
|
};
|
|
3461
3745
|
};
|
|
3462
3746
|
};
|
|
3747
|
+
/**
|
|
3748
|
+
* 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 (only month today, 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
|
+
*/
|
|
3751
|
+
getKeyUsage: {
|
|
3752
|
+
responses: {
|
|
3753
|
+
/** @description The key's usage, limits and reset time. */
|
|
3754
|
+
200: {
|
|
3755
|
+
content: {
|
|
3756
|
+
"application/json": components["schemas"]["KeyUsage"];
|
|
3757
|
+
};
|
|
3758
|
+
};
|
|
3759
|
+
/** @description `code: "PARTNER_KEY_REQUIRED"` - no recognized partner API key. An absent, malformed and unrecognized key all answer the same way. */
|
|
3760
|
+
401: {
|
|
3761
|
+
content: {
|
|
3762
|
+
"application/json": components["schemas"]["ErrorResponse"];
|
|
3763
|
+
};
|
|
3764
|
+
};
|
|
3765
|
+
/** @description `code: "RATE_LIMITED"` - more than 60 requests in a minute from this address, or for this key. */
|
|
3766
|
+
429: {
|
|
3767
|
+
headers: {
|
|
3768
|
+
/** @description Seconds until next allowed request */
|
|
3769
|
+
"Retry-After"?: number;
|
|
3770
|
+
};
|
|
3771
|
+
content: {
|
|
3772
|
+
"application/json": components["schemas"]["ErrorResponse"];
|
|
3773
|
+
};
|
|
3774
|
+
};
|
|
3775
|
+
/** @description `code: "USAGE_UNAVAILABLE"` - usage could not be read right now. Retry shortly; the route never answers a guessed zero. */
|
|
3776
|
+
503: {
|
|
3777
|
+
content: {
|
|
3778
|
+
"application/json": components["schemas"]["ErrorResponse"];
|
|
3779
|
+
};
|
|
3780
|
+
};
|
|
3781
|
+
};
|
|
3782
|
+
};
|
|
3463
3783
|
/**
|
|
3464
3784
|
* Get agent feedback for a product
|
|
3465
3785
|
* @description Returns feedback submitted by AI agents about their experience using a product. Includes aggregate stats and individual reviews.
|
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
/** The ora contract version (spec info.version) these types were generated from. */
|
|
2
|
-
export declare const BUILT_AGAINST = "1.
|
|
2
|
+
export declare const BUILT_AGAINST = "1.38.0";
|