ax 0.8.1 → 0.9.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 +18 -5
- package/dist/api/agent-files.d.ts +48 -0
- package/dist/api/deep-journey.d.ts +11 -3
- package/dist/contract/types.gen.d.ts +124 -23
- package/dist/contract/version.d.ts +1 -1
- package/dist/index.cjs +161 -44
- package/dist/index.d.ts +1 -0
- package/dist/index.js +159 -44
- package/dist/main.cjs +65 -62
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -31,6 +31,7 @@ Five commands:
|
|
|
31
31
|
- **`deep-journey <url>`** — run a real AI agent at a site on one of ora's curated tasks through the public journey API: no key, no workspace. A partner API key unlocks free-text tasks (`--task`) and a larger allowance.
|
|
32
32
|
- **`journey "<intent>"`** — send a real AI agent (claude-code, codex, …) at a site and watch its navigation live as a boxed node-graph, then get the scored insight, tokens, and cost. Partner-only: needs an `ORA_API_KEY` (see [For ora partners](#for-ora-partners)).
|
|
33
33
|
- **`skill [name]`** — list, print, or install ora's agent skills, digest-verified from the public registry.
|
|
34
|
+
- **`generate-files <domain>`** — draft the agent discovery files a site publishes about itself (`ard.json`, `ai-catalog.json`, `poppy.json`) into `.well-known/`, filled in from ora's last scan of the domain.
|
|
34
35
|
|
|
35
36
|
## audit
|
|
36
37
|
|
|
@@ -229,11 +230,11 @@ Runs a real AI agent at a site through ora's **public** journey API — no key,
|
|
|
229
230
|
For the 4-layer readiness audit, run: ax audit stripe.com
|
|
230
231
|
```
|
|
231
232
|
|
|
232
|
-
Anonymous callers run curated intents (`pricing`, `signup`, `api-docs`, `integrate`, `support`, …) — list them with `GET https://ora.ai/api/journey/intents`, and the accepted agents with `GET https://ora.ai/api/journey/agents`. The public caps are 100 runs per rolling 24h per target and
|
|
233
|
+
Anonymous callers run curated intents (`pricing`, `signup`, `api-docs`, `integrate`, `support`, …) — list them with `GET https://ora.ai/api/journey/intents`, and the accepted agents with `GET https://ora.ai/api/journey/agents`. The public caps are 100 runs per rolling 24h per target and 20 runs per 24h per IP (plus a 20/min burst limit and a shared ceiling of 3,000 anonymous runs a day across all callers); a target at its cap answers with the most recent stored run (`rate_limited: true`) instead of an error, so repeat CI invocations are cheap. Verdict and step count come from ora's contract as-is — the CLI never re-judges a run.
|
|
233
234
|
|
|
234
235
|
**Keyed tier:** an ora-issued partner API key (`--api-key`, or `ORA_PARTNER_API_KEY` / `ORA_SCAN_API_KEY` in the environment) unlocks `--task` — a free-text task of 4–300 characters that replaces the curated intent — and moves the caller to an allowance of 1000 runs per rolling 24h per key with no per-target cap and no burst guard. Keys are issued manually by ora (no self-serve signup). A wrong or unrecognized key with a *curated* intent silently degrades to the anonymous tier; `--task` without a recognized key is an error.
|
|
235
236
|
|
|
236
|
-
|
|
237
|
+
The CLI always follows the run's stream to the end, `--no-stream` included, because ora saves a finished run from inside the stream. If the stream drops or goes quiet (no frames for 120s), the CLI reopens it, which resumes the same run without re-running the agent. A stream `429` is waited out (up to 60s) before reopening, and a `404` or auth error ends the command at once. Only after five failed reopens does it fall back to polling the run detail, within a 15-minute budget shared with the stream.
|
|
237
238
|
|
|
238
239
|
| Flag | Effect |
|
|
239
240
|
|---|---|
|
|
@@ -241,7 +242,7 @@ If the live stream goes quiet (no frames for 120s) the CLI does not abandon the
|
|
|
241
242
|
| `--task <text>` | Free-text task — needs a partner API key; mutually exclusive with `--intent` |
|
|
242
243
|
| `--api-key <k>` | ora partner API key; also read from `ORA_PARTNER_API_KEY` (then `ORA_SCAN_API_KEY`) |
|
|
243
244
|
| `--agent <id>` | Agent from the public roster (default: ora's pick) |
|
|
244
|
-
| `--no-stream` |
|
|
245
|
+
| `--no-stream` | Hide the live trajectory view and print only the final result |
|
|
245
246
|
| `--json` | Print the terminal run detail (verdict, step_count, result) as JSON |
|
|
246
247
|
|
|
247
248
|
deep-journey exit codes: `0` run succeeded (any verdict) · `1` run failed · `2` usage error · `3` API unreachable / rate-limited.
|
|
@@ -259,6 +260,18 @@ ax skill --json # the raw registry index
|
|
|
259
260
|
|
|
260
261
|
Skills come from ora's public registry (`https://ora.ai/.well-known/agent-skills/`) and every byte is verified against the registry's sha256 digest before it is printed or installed. Skill content is never bundled into this package. `--dir <path>` overrides the install directory, and `--json` prints the registry index as JSON instead of the formatted list.
|
|
261
262
|
|
|
263
|
+
## generate-files
|
|
264
|
+
|
|
265
|
+
```
|
|
266
|
+
ax generate-files example.com # writes ./.well-known/{ard,ai-catalog,poppy}.json
|
|
267
|
+
ax generate-files example.com --out public # writes public/.well-known/... (your site's static root)
|
|
268
|
+
ax generate-files example.com --json # ora's payload, files + notes, nothing written
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
Drafts the files agents look for under a site's `/.well-known/`: an [Agentic Resource Discovery](https://agenticresourcediscovery.org/) catalog (`ard.json`, the same document as `ai-catalog.json` for the [AI Catalog Standard](https://ai-catalog.io/)'s path) and a [Personal Agent Protocol](https://personalagentprotocol.org/docs/spec) `poppy.json`. ora builds them from what it already knows about the domain (its last scan; no new crawl), so run `ax audit` first for a domain ora has never scanned - without a scan the catalog lists only the website. Every catalog entry is anchored to your domain, not to ora. The `poppy.json` is the minimal valid document (signed-out browsing); the OAuth issuer and APIs ora saw are printed as notes rather than written into it, because naming them is only correct once they implement the protocol. These are drafts: read each file and its notes before you publish.
|
|
272
|
+
|
|
273
|
+
Nothing is overwritten: if any target file exists, nothing is written and the command exits `2` - pass `--force` to overwrite, or `--out <dir>` to write elsewhere. Exit codes: `0` written, `2` usage (bad domain, files exist), `3` API. Same files as the web generator at [directory.ora.ai/generate](https://directory.ora.ai/generate) and `GET https://ora.ai/api/agent-files/{domain}`.
|
|
274
|
+
|
|
262
275
|
## Library use
|
|
263
276
|
|
|
264
277
|
The same contract-typed client the CLI uses is importable:
|
|
@@ -270,7 +283,7 @@ const { result } = await audit("stripe.com");
|
|
|
270
283
|
console.log(result.score, result.grade, result.topFixes);
|
|
271
284
|
```
|
|
272
285
|
|
|
273
|
-
`result` is the raw versioned audit payload (`AuditScanResult` / `AuditScoreResult`, generated from ora's OpenAPI spec). `fetchSkill` / `fetchSkillIndex` expose the digest-verified skill registry.
|
|
286
|
+
`result` is the raw versioned audit payload (`AuditScanResult` / `AuditScoreResult`, generated from ora's OpenAPI spec). `fetchSkill` / `fetchSkillIndex` expose the digest-verified skill registry, and `fetchAgentFiles` the agent files generator.
|
|
274
287
|
|
|
275
288
|
The public journey client is exported too — the same no-key path as `ax deep-journey`:
|
|
276
289
|
|
|
@@ -362,7 +375,7 @@ A `.env` in the working directory is read on startup — copy `.env.example` and
|
|
|
362
375
|
|
|
363
376
|
| Var | Used by | Default | Purpose |
|
|
364
377
|
|---|---|---|---|
|
|
365
|
-
| `ORA_API_URL` | audit, deep-journey, skill | `https://ora.ai` | Public API base (no auth) |
|
|
378
|
+
| `ORA_API_URL` | audit, deep-journey, skill, generate-files | `https://ora.ai` | Public API base (no auth) |
|
|
366
379
|
| `ORA_PLATFORM_URL` | journey, audit `--tunnel ora` | `https://api.agentfront.sh` | Authenticated platform API base |
|
|
367
380
|
| `ORA_TUNNEL` | audit | — (optional) | `ora` opens ora's own tunnel for a local target (same as `--tunnel ora`) |
|
|
368
381
|
| `ORA_TUNNEL_CMD` | audit | — (optional) | Tunnel command for a local target (same as `--tunnel-cmd`); wins over `ORA_TUNNEL` |
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
export interface AgentFile {
|
|
2
|
+
/** Where the domain serves the file, e.g. "/.well-known/ard.json". */
|
|
3
|
+
path: string;
|
|
4
|
+
spec: {
|
|
5
|
+
name: string;
|
|
6
|
+
version: string;
|
|
7
|
+
url: string;
|
|
8
|
+
};
|
|
9
|
+
/** The JSON document to publish at `path`. */
|
|
10
|
+
content: Record<string, unknown>;
|
|
11
|
+
/** What to review or add before publishing. */
|
|
12
|
+
notes: string[];
|
|
13
|
+
}
|
|
14
|
+
export interface AgentFilesBundle {
|
|
15
|
+
domain: string;
|
|
16
|
+
productName: string;
|
|
17
|
+
/** When ora last scanned the domain; null when it never has. */
|
|
18
|
+
scannedAt: string | null;
|
|
19
|
+
files: AgentFile[];
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Any failure to get the files from ora. `status` is the HTTP status when ora
|
|
23
|
+
* answered (400 = not a public domain), and `payload` the error body exactly as
|
|
24
|
+
* served, which is what `--json` prints.
|
|
25
|
+
*/
|
|
26
|
+
export declare class AgentFilesApiError extends Error {
|
|
27
|
+
readonly status: number | null;
|
|
28
|
+
readonly payload: unknown;
|
|
29
|
+
constructor(message: string, options?: {
|
|
30
|
+
status?: number | null;
|
|
31
|
+
payload?: unknown;
|
|
32
|
+
});
|
|
33
|
+
}
|
|
34
|
+
export interface AgentFilesOptions {
|
|
35
|
+
/** Base URL override; otherwise $ORA_API_URL, otherwise https://ora.ai. */
|
|
36
|
+
baseUrl?: string;
|
|
37
|
+
}
|
|
38
|
+
export declare function isSafeAgentFilePath(path: string): boolean;
|
|
39
|
+
/**
|
|
40
|
+
* Drop trailing slashes with a scan rather than `/\/+$/`: that regex retries
|
|
41
|
+
* at every `/` of a long run that is not at the end, quadratic on input a
|
|
42
|
+
* caller controls (CodeQL js/polynomial-redos).
|
|
43
|
+
*/
|
|
44
|
+
export declare function trimTrailingSlashes(value: string): string;
|
|
45
|
+
/** Strip a scheme and trailing slash so `https://example.com/` reads as a domain. */
|
|
46
|
+
export declare function normalizeDomainInput(input: string): string;
|
|
47
|
+
/** Fetch the drafted files for `domain` from ora. */
|
|
48
|
+
export declare function fetchAgentFiles(domain: string, options?: AgentFilesOptions): Promise<AgentFilesBundle>;
|
|
@@ -55,8 +55,16 @@ export interface DeepJourneyOptions {
|
|
|
55
55
|
baseUrl?: string;
|
|
56
56
|
/** Abort when the stream is silent for this long (default 120s). */
|
|
57
57
|
idleMs?: number;
|
|
58
|
-
/**
|
|
58
|
+
/**
|
|
59
|
+
* No live view: `onTrajectory` is never called. The run is still followed
|
|
60
|
+
* over the stream, because the stream is what saves the finished run.
|
|
61
|
+
*/
|
|
59
62
|
noStream?: boolean;
|
|
63
|
+
/** Pause between stream reopens after a drop (default 2s). */
|
|
64
|
+
reopenPauseMs?: number;
|
|
65
|
+
/** Total time to follow a running run, streaming plus polling (default 15min). */
|
|
66
|
+
followBudgetMs?: number;
|
|
67
|
+
/** Detail polling, the last resort once every stream reopen has failed. */
|
|
60
68
|
pollEveryMs?: number;
|
|
61
69
|
pollLimit?: number;
|
|
62
70
|
}
|
|
@@ -88,8 +96,8 @@ export declare function formatWait(ms: number): string;
|
|
|
88
96
|
export declare function fetchRunDetail(base: string, runId: string): Promise<JourneyRunDetail>;
|
|
89
97
|
/**
|
|
90
98
|
* Run a deep journey against `target` and resolve with the terminal detail.
|
|
91
|
-
*
|
|
92
|
-
*
|
|
99
|
+
* Follows a running run's stream to its terminal frame (progress lines via
|
|
100
|
+
* `options.progress`); `noStream` only withholds `onTrajectory`. A per-target-capped trigger is
|
|
93
101
|
* NOT an error: ora answers with the most recent stored run for that target,
|
|
94
102
|
* and the outcome carries `cached: true` plus `retryAfterMs`.
|
|
95
103
|
*/
|
|
@@ -26,7 +26,7 @@ export interface paths {
|
|
|
26
26
|
"/api/scan/stream": {
|
|
27
27
|
/**
|
|
28
28
|
* Stream an agent-readiness scan as Server-Sent Events
|
|
29
|
-
* @description Runs a full agent-readiness scan on the given URL and streams progress as text/event-stream. 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. The stream emits a `kind_detecting` event immediately after the cheap reachability probe, followed by exactly one `kind_detected` event with payload `{ kind: 'domain' | 'mcp' | 'mcp-app', mcpUrl?: string, embeddedMcpUrls?: string[], hint?: string }` once URL-kind detection resolves.
|
|
29
|
+
* @description Runs a full agent-readiness scan on the given URL and streams progress as text/event-stream. 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. The stream emits a `kind_detecting` event immediately after the cheap reachability probe, followed by exactly one `kind_detected` event with payload `{ kind: 'domain' | 'mcp' | 'mcp-app', mcpUrl?: string, embeddedMcpUrls?: string[], hint?: string }` once URL-kind detection resolves. Progress events follow (the 200 response lists every event type), and finally `scan_complete` whose payload mirrors the ScanResult schema (including the optional `urlKind` field indicating the detected kind). The same freshness gate as POST /api/scan applies: a hit is a `kind_detected` frame followed by the terminal `scan_complete` event, rather than a full run. 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.
|
|
30
30
|
*/
|
|
31
31
|
get: operations["scanDomainStream"];
|
|
32
32
|
};
|
|
@@ -40,7 +40,7 @@ export interface paths {
|
|
|
40
40
|
"/api/score/{domain}": {
|
|
41
41
|
/**
|
|
42
42
|
* Get cached score for a domain
|
|
43
|
-
* @description Returns the most recent cached scan result for the given domain. Read-only: never triggers a scan. On miss (404) or when the previous scan got stuck mid-flight (200 with `analysisStatus: "stuck"`), the response carries a structured `next_action` envelope pointing at `POST /api/scan` so agent callers have a machine-parseable next step. Successful responses are cached for 1 hour; stuck, 404, and ephemeral (disposable, `urlKind: "ephemeral"`) responses are uncached (`Cache-Control: no-store`) so a successful re-scan is observable immediately and a deleted disposable row is never served from cache. Rate limited to 10 requests per minute per IP - returns 429 if exceeded.
|
|
43
|
+
* @description Returns the most recent cached scan result for the given domain. Read-only: never triggers a scan. On miss (404) or when the previous scan got stuck mid-flight (200 with `analysisStatus: "stuck"`), the response carries a structured `next_action` envelope pointing at `POST /api/scan` so agent callers have a machine-parseable next step. Successful responses are cached for 1 hour; stuck, 404, and ephemeral (disposable, `urlKind: "ephemeral"`) responses are uncached (`Cache-Control: no-store`) so a successful re-scan is observable immediately and a deleted disposable row is never served from cache. Rate limited to 10 requests per minute per IP - returns 429 if exceeded. A scan API key exempts the caller, since this is the poll target for keyed scanning.
|
|
44
44
|
*/
|
|
45
45
|
get: operations["getScore"];
|
|
46
46
|
};
|
|
@@ -128,6 +128,13 @@ export interface paths {
|
|
|
128
128
|
*/
|
|
129
129
|
get: operations["ardGetCatalogDump"];
|
|
130
130
|
};
|
|
131
|
+
"/api/agent-files/{domain}": {
|
|
132
|
+
/**
|
|
133
|
+
* 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.1). 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. 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
|
+
*/
|
|
136
|
+
get: operations["generateAgentFiles"];
|
|
137
|
+
};
|
|
131
138
|
"/api/ard/jwks": {
|
|
132
139
|
/**
|
|
133
140
|
* Get the public JWK set for verifying signed attestations (Agentic Resource Discovery)
|
|
@@ -145,7 +152,7 @@ export interface paths {
|
|
|
145
152
|
"/api/journey/runs": {
|
|
146
153
|
/**
|
|
147
154
|
* Run an agent journey against a domain
|
|
148
|
-
* @description Triggers a real agent run: an AI agent (harness + model) attempts a task (an intent) against the given domain, and ora records the trajectory and derives insights. Two-step flow: this endpoint returns fast with a run record whose `stream_url` serves the live trajectory as Server-Sent Events;
|
|
155
|
+
* @description Triggers a real agent run: an AI agent (harness + model) attempts a task (an intent) against the given domain, and ora records the trajectory and derives insights. Two-step flow: this endpoint returns fast with a run record whose `stream_url` serves the live trajectory as Server-Sent Events; the stream is also what saves the finished run, so hold it open until its `result` or `error` frame (reopen it if the connection drops; it resumes the same run without re-executing). GET /api/journey/runs/{id} reads what a stream saved: a run nobody streams stays `running`. Two caller tiers. Anonymous: curated intents only (see GET /api/journey/intents) - the server derives the actual agent prompt from the intent id, so no free-text prompt can reach the engine. Keyed: a caller presenting an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora) may instead send bounded free text (`intent.custom`, 4 to 300 characters, with `intent.domain` required), which the server anchors to the requested domain before dispatch and echoes back on the 201. Free text without a recognized key is a 401 with code CUSTOM_INTENT_REQUIRES_KEY; a curated body with a missing or unrecognized key is never an error and simply runs on the anonymous tier. The keyed free-text tier is also reachable from the ora CLI (ax deep-journey --task, v0.5+). Only publicly runnable agents are accepted (see GET /api/journey/agents). Unknown body fields are rejected (strict schema). Anonymous rate limits, three ways: a 20-per-minute burst cap per IP; a per-target cap of 100 runs per rolling 24h per (domain, intent, harness, model) - when a target is over the cap the response is HTTP 200 with the most recent stored run for that target (`rate_limited: true`) plus Retry-After, the freshness analog: a denied trigger still returns the newest result and consumes nothing; and a durable per-caller cap of 20 runs per rolling 24h per IP - exceeded, that one is a real 429 with `retry_after_ms` (there is no cached result to serve for a caller). On top of those, all anonymous callers together share a ceiling of 3000 runs per rolling 24h; when it is full every anonymous trigger gets the same 429 with `retry_after_ms` until the oldest run ages out, while keyed callers are unaffected. Keyed rate limit, one way: 1000 runs per rolling 24h per key, exhaustion being the same 429 with `retry_after_ms`. A keyed caller skips both the burst cap and the per-target cap - free text fragments the target key, so a per-target window over it could never fill. Successful and capped responses carry X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset headers describing exactly one window: the per-target window on an anonymous response, the per-key caller window on a keyed one. Note: journey insights use the 5-layer journey taxonomy (discovery, identity, access, payments, experience), deliberately distinct from the 4 scoring layers of the audit report (POST /api/scan) - never map between the two.
|
|
149
156
|
*/
|
|
150
157
|
post: operations["createJourneyRun"];
|
|
151
158
|
};
|
|
@@ -424,7 +431,7 @@ export interface components {
|
|
|
424
431
|
* @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.
|
|
425
432
|
* @enum {string}
|
|
426
433
|
*/
|
|
427
|
-
contractVersion: "1.
|
|
434
|
+
contractVersion: "1.30.0";
|
|
428
435
|
/**
|
|
429
436
|
* @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.
|
|
430
437
|
* @enum {boolean}
|
|
@@ -462,10 +469,14 @@ export interface components {
|
|
|
462
469
|
/** @description Why this request is the recommended next step */
|
|
463
470
|
reason: string;
|
|
464
471
|
};
|
|
465
|
-
/** @description Experimental (no stability guarantee): competitive context
|
|
472
|
+
/** @description Experimental (no stability guarantee): competitive context drawn from the leaderboard, present only when the request carries ?competitors=1. Null when the domain is unranked or the leaderboard read failed. Shape may change on any release. */
|
|
466
473
|
competitors?: {
|
|
467
474
|
[key: string]: unknown;
|
|
468
475
|
} | null;
|
|
476
|
+
/** @description Experimental (no stability guarantee): the scan scored against what the site is, present only when the request carries ?include=siteType. Null when the scan has no layers to score. Shape may change on any release. */
|
|
477
|
+
siteType?: {
|
|
478
|
+
[key: string]: unknown;
|
|
479
|
+
} | null;
|
|
469
480
|
};
|
|
470
481
|
AuditScoreResult: {
|
|
471
482
|
domain: string;
|
|
@@ -623,7 +634,7 @@ export interface components {
|
|
|
623
634
|
* @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.
|
|
624
635
|
* @enum {string}
|
|
625
636
|
*/
|
|
626
|
-
contractVersion: "1.
|
|
637
|
+
contractVersion: "1.30.0";
|
|
627
638
|
/** @description Wall-clock duration of the scan that produced this stored result */
|
|
628
639
|
durationMs: number | null;
|
|
629
640
|
/**
|
|
@@ -656,10 +667,14 @@ export interface components {
|
|
|
656
667
|
/** @description Why this request is the recommended next step */
|
|
657
668
|
reason: string;
|
|
658
669
|
};
|
|
659
|
-
/** @description Experimental (no stability guarantee): competitive context
|
|
670
|
+
/** @description Experimental (no stability guarantee): competitive context drawn from the leaderboard, present only when the request carries ?competitors=1. Null when the domain is unranked or the leaderboard read failed. Shape may change on any release. */
|
|
660
671
|
competitors?: {
|
|
661
672
|
[key: string]: unknown;
|
|
662
673
|
} | null;
|
|
674
|
+
/** @description Experimental (no stability guarantee): the scan scored against what the site is, present only when the request carries ?include=siteType. Null when the scan has no layers to score. Shape may change on any release. */
|
|
675
|
+
siteType?: {
|
|
676
|
+
[key: string]: unknown;
|
|
677
|
+
} | null;
|
|
663
678
|
};
|
|
664
679
|
/** @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. */
|
|
665
680
|
CheckCatalog: {
|
|
@@ -667,7 +682,7 @@ export interface components {
|
|
|
667
682
|
* @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.
|
|
668
683
|
* @enum {string}
|
|
669
684
|
*/
|
|
670
|
-
contractVersion: "1.
|
|
685
|
+
contractVersion: "1.30.0";
|
|
671
686
|
/** @description The four scored layers in scoring order, with display name and current weight. */
|
|
672
687
|
layers: {
|
|
673
688
|
/** @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'. */
|
|
@@ -766,7 +781,7 @@ export interface components {
|
|
|
766
781
|
* @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.
|
|
767
782
|
* @enum {string}
|
|
768
783
|
*/
|
|
769
|
-
contractVersion: "1.
|
|
784
|
+
contractVersion: "1.30.0";
|
|
770
785
|
/** @description The apex domain derived from the requested URL. */
|
|
771
786
|
domain: string;
|
|
772
787
|
/** @description The normalized URL the run targeted. */
|
|
@@ -2161,6 +2176,35 @@ export interface components {
|
|
|
2161
2176
|
/** @description Optional recovery hint (e.g. /api/scan on NOT_FOUND). */
|
|
2162
2177
|
next?: string;
|
|
2163
2178
|
};
|
|
2179
|
+
/** @description Draft agent discovery files for one domain, returned by GET /api/agent-files/{domain}. */
|
|
2180
|
+
AgentFilesBundle: {
|
|
2181
|
+
/** @description The domain the files speak for (leading www. dropped). */
|
|
2182
|
+
domain: string;
|
|
2183
|
+
/** @description The product name used in the files; the domain itself when ora knows no name. */
|
|
2184
|
+
productName: string;
|
|
2185
|
+
/**
|
|
2186
|
+
* Format: date-time
|
|
2187
|
+
* @description When ora last scanned the domain; null when it never has, in which case the files carry only what the domain alone implies.
|
|
2188
|
+
*/
|
|
2189
|
+
scannedAt: string | null;
|
|
2190
|
+
files: components["schemas"]["AgentFile"][];
|
|
2191
|
+
};
|
|
2192
|
+
AgentFile: {
|
|
2193
|
+
/** @description Where the domain serves the file, e.g. /.well-known/ard.json. */
|
|
2194
|
+
path: string;
|
|
2195
|
+
/** @description The standard the file follows. */
|
|
2196
|
+
spec: {
|
|
2197
|
+
name: string;
|
|
2198
|
+
version: string;
|
|
2199
|
+
url: string;
|
|
2200
|
+
};
|
|
2201
|
+
/** @description The JSON document to publish at path. */
|
|
2202
|
+
content: {
|
|
2203
|
+
[key: string]: unknown;
|
|
2204
|
+
};
|
|
2205
|
+
/** @description What to review or add before publishing, in plain sentences. */
|
|
2206
|
+
notes: string[];
|
|
2207
|
+
};
|
|
2164
2208
|
McpAuthRequiredResponse: {
|
|
2165
2209
|
/** @description Why the MCP server could not be inspected. */
|
|
2166
2210
|
error: string;
|
|
@@ -2281,10 +2325,10 @@ export interface operations {
|
|
|
2281
2325
|
query?: {
|
|
2282
2326
|
/** @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. */
|
|
2283
2327
|
competitors?: "1";
|
|
2284
|
-
/** @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
|
|
2328
|
+
/** @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. */
|
|
2285
2329
|
format?: "audit";
|
|
2286
|
-
/** @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). */
|
|
2287
|
-
include?:
|
|
2330
|
+
/** @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). 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. */
|
|
2331
|
+
include?: string;
|
|
2288
2332
|
};
|
|
2289
2333
|
};
|
|
2290
2334
|
requestBody: {
|
|
@@ -2309,6 +2353,13 @@ export interface operations {
|
|
|
2309
2353
|
force?: boolean;
|
|
2310
2354
|
/** @description Store the result as disposable: it is excluded from the leaderboard, the sites-scanned coverage count, research statistics, and score history, is served with Cache-Control: no-store, and is deleted after a few days. Intended for a local site exposed through a tunnel, or any host that will not exist tomorrow. Public tunnel hostnames (trycloudflare.com, ngrok, and similar) are stored this way whether or not the flag is set. Rejected with 400 EPHEMERAL_CLOBBER when the domain already has a real stored scan, since a disposable result would replace it. */
|
|
2311
2355
|
ephemeral?: boolean;
|
|
2356
|
+
/**
|
|
2357
|
+
* @description Optional. With `?include=siteType`, scores the response's `siteType` reading against this type instead of the inferred one. Absent, the type is inferred.
|
|
2358
|
+
* @enum {string}
|
|
2359
|
+
*/
|
|
2360
|
+
siteType?: "content" | "business" | "app" | "store";
|
|
2361
|
+
/** @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. */
|
|
2362
|
+
activeProbes?: boolean;
|
|
2312
2363
|
};
|
|
2313
2364
|
};
|
|
2314
2365
|
};
|
|
@@ -2455,7 +2506,7 @@ export interface operations {
|
|
|
2455
2506
|
};
|
|
2456
2507
|
/**
|
|
2457
2508
|
* Stream an agent-readiness scan as Server-Sent Events
|
|
2458
|
-
* @description Runs a full agent-readiness scan on the given URL and streams progress as text/event-stream. 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. The stream emits a `kind_detecting` event immediately after the cheap reachability probe, followed by exactly one `kind_detected` event with payload `{ kind: 'domain' | 'mcp' | 'mcp-app', mcpUrl?: string, embeddedMcpUrls?: string[], hint?: string }` once URL-kind detection resolves.
|
|
2509
|
+
* @description Runs a full agent-readiness scan on the given URL and streams progress as text/event-stream. 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. The stream emits a `kind_detecting` event immediately after the cheap reachability probe, followed by exactly one `kind_detected` event with payload `{ kind: 'domain' | 'mcp' | 'mcp-app', mcpUrl?: string, embeddedMcpUrls?: string[], hint?: string }` once URL-kind detection resolves. Progress events follow (the 200 response lists every event type), and finally `scan_complete` whose payload mirrors the ScanResult schema (including the optional `urlKind` field indicating the detected kind). The same freshness gate as POST /api/scan applies: a hit is a `kind_detected` frame followed by the terminal `scan_complete` event, rather than a full run. 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.
|
|
2459
2510
|
*/
|
|
2460
2511
|
scanDomainStream: {
|
|
2461
2512
|
parameters: {
|
|
@@ -2470,12 +2521,18 @@ export interface operations {
|
|
|
2470
2521
|
force?: "1";
|
|
2471
2522
|
/** @description Pass 1 to store the result as disposable - the same flag POST /api/scan takes in its body, with the same 400 EPHEMERAL_CLOBBER refusal when the domain already has a real stored scan. */
|
|
2472
2523
|
ephemeral?: "1";
|
|
2473
|
-
/** @description Pass
|
|
2524
|
+
/** @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. */
|
|
2525
|
+
activeProbes?: "1";
|
|
2526
|
+
/** @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. */
|
|
2474
2527
|
format?: "audit";
|
|
2528
|
+
/** @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. */
|
|
2529
|
+
include?: "siteType";
|
|
2530
|
+
/** @description Read-time lens for `include=siteType`: scores the scan against this type instead of the resolved one, without rescanning or storing anything. An unrecognized value is ignored, not rejected. */
|
|
2531
|
+
siteType?: "content" | "business" | "app" | "store";
|
|
2475
2532
|
};
|
|
2476
2533
|
};
|
|
2477
2534
|
responses: {
|
|
2478
|
-
/** @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
|
|
2535
|
+
/** @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. */
|
|
2479
2536
|
200: {
|
|
2480
2537
|
content: {
|
|
2481
2538
|
"text/event-stream": string;
|
|
@@ -2536,17 +2593,19 @@ export interface operations {
|
|
|
2536
2593
|
};
|
|
2537
2594
|
/**
|
|
2538
2595
|
* Get cached score for a domain
|
|
2539
|
-
* @description Returns the most recent cached scan result for the given domain. Read-only: never triggers a scan. On miss (404) or when the previous scan got stuck mid-flight (200 with `analysisStatus: "stuck"`), the response carries a structured `next_action` envelope pointing at `POST /api/scan` so agent callers have a machine-parseable next step. Successful responses are cached for 1 hour; stuck, 404, and ephemeral (disposable, `urlKind: "ephemeral"`) responses are uncached (`Cache-Control: no-store`) so a successful re-scan is observable immediately and a deleted disposable row is never served from cache. Rate limited to 10 requests per minute per IP - returns 429 if exceeded.
|
|
2596
|
+
* @description Returns the most recent cached scan result for the given domain. Read-only: never triggers a scan. On miss (404) or when the previous scan got stuck mid-flight (200 with `analysisStatus: "stuck"`), the response carries a structured `next_action` envelope pointing at `POST /api/scan` so agent callers have a machine-parseable next step. Successful responses are cached for 1 hour; stuck, 404, and ephemeral (disposable, `urlKind: "ephemeral"`) responses are uncached (`Cache-Control: no-store`) so a successful re-scan is observable immediately and a deleted disposable row is never served from cache. Rate limited to 10 requests per minute per IP - returns 429 if exceeded. A scan API key exempts the caller, since this is the poll target for keyed scanning.
|
|
2540
2597
|
*/
|
|
2541
2598
|
getScore: {
|
|
2542
2599
|
parameters: {
|
|
2543
2600
|
query?: {
|
|
2544
2601
|
/** @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. */
|
|
2545
2602
|
competitors?: "1";
|
|
2546
|
-
/** @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
|
|
2603
|
+
/** @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. */
|
|
2547
2604
|
format?: "audit";
|
|
2548
|
-
/** @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). */
|
|
2549
|
-
include?:
|
|
2605
|
+
/** @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). 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. */
|
|
2606
|
+
include?: string;
|
|
2607
|
+
/** @description Read-time lens for `include=siteType`: scores the scan against this type instead of the resolved one, without rescanning or storing anything. An unrecognized value is ignored, not rejected. */
|
|
2608
|
+
siteType?: "content" | "business" | "app" | "store";
|
|
2550
2609
|
};
|
|
2551
2610
|
path: {
|
|
2552
2611
|
/** @description The domain to look up (e.g. stripe.com). URL-encoded full URLs are normalized to their hostname. */
|
|
@@ -3036,6 +3095,48 @@ export interface operations {
|
|
|
3036
3095
|
};
|
|
3037
3096
|
};
|
|
3038
3097
|
};
|
|
3098
|
+
/**
|
|
3099
|
+
* Draft a domain's own agent discovery files (ard.json, ai-catalog.json, poppy.json)
|
|
3100
|
+
* @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.1). 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. 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>`.
|
|
3101
|
+
*/
|
|
3102
|
+
generateAgentFiles: {
|
|
3103
|
+
parameters: {
|
|
3104
|
+
path: {
|
|
3105
|
+
/** @description A public host such as example.com (a full https:// URL without a path is also accepted). IPs, ports, paths and localhost are refused. */
|
|
3106
|
+
domain: string;
|
|
3107
|
+
};
|
|
3108
|
+
};
|
|
3109
|
+
responses: {
|
|
3110
|
+
/** @description The drafted files. */
|
|
3111
|
+
200: {
|
|
3112
|
+
content: {
|
|
3113
|
+
"application/json": components["schemas"]["AgentFilesBundle"];
|
|
3114
|
+
};
|
|
3115
|
+
};
|
|
3116
|
+
/** @description The domain was spelled differently from its canonical form (www., upper case, a trailing dot); Location is /api/agent-files/<domain>. */
|
|
3117
|
+
308: {
|
|
3118
|
+
content: never;
|
|
3119
|
+
};
|
|
3120
|
+
/** @description INVALID_ARGUMENT - not a public domain. */
|
|
3121
|
+
400: {
|
|
3122
|
+
content: {
|
|
3123
|
+
"application/json": components["schemas"]["ArdErrorResponse"];
|
|
3124
|
+
};
|
|
3125
|
+
};
|
|
3126
|
+
/** @description RATE_LIMIT_EXCEEDED - max 60 requests per minute per IP. */
|
|
3127
|
+
429: {
|
|
3128
|
+
content: {
|
|
3129
|
+
"application/json": components["schemas"]["ArdErrorResponse"];
|
|
3130
|
+
};
|
|
3131
|
+
};
|
|
3132
|
+
/** @description INTERNAL_ERROR */
|
|
3133
|
+
500: {
|
|
3134
|
+
content: {
|
|
3135
|
+
"application/json": components["schemas"]["ArdErrorResponse"];
|
|
3136
|
+
};
|
|
3137
|
+
};
|
|
3138
|
+
};
|
|
3139
|
+
};
|
|
3039
3140
|
/**
|
|
3040
3141
|
* Get the public JWK set for verifying signed attestations (Agentic Resource Discovery)
|
|
3041
3142
|
* @description Returns the public JSON Web Key Set used to verify ora's signed Agentic Resource Discovery (ARD) scorecard attestations. Also served at /.well-known/jwks.json via a rewrite.
|
|
@@ -3066,7 +3167,7 @@ export interface operations {
|
|
|
3066
3167
|
};
|
|
3067
3168
|
/**
|
|
3068
3169
|
* Run an agent journey against a domain
|
|
3069
|
-
* @description Triggers a real agent run: an AI agent (harness + model) attempts a task (an intent) against the given domain, and ora records the trajectory and derives insights. Two-step flow: this endpoint returns fast with a run record whose `stream_url` serves the live trajectory as Server-Sent Events;
|
|
3170
|
+
* @description Triggers a real agent run: an AI agent (harness + model) attempts a task (an intent) against the given domain, and ora records the trajectory and derives insights. Two-step flow: this endpoint returns fast with a run record whose `stream_url` serves the live trajectory as Server-Sent Events; the stream is also what saves the finished run, so hold it open until its `result` or `error` frame (reopen it if the connection drops; it resumes the same run without re-executing). GET /api/journey/runs/{id} reads what a stream saved: a run nobody streams stays `running`. Two caller tiers. Anonymous: curated intents only (see GET /api/journey/intents) - the server derives the actual agent prompt from the intent id, so no free-text prompt can reach the engine. Keyed: a caller presenting an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora) may instead send bounded free text (`intent.custom`, 4 to 300 characters, with `intent.domain` required), which the server anchors to the requested domain before dispatch and echoes back on the 201. Free text without a recognized key is a 401 with code CUSTOM_INTENT_REQUIRES_KEY; a curated body with a missing or unrecognized key is never an error and simply runs on the anonymous tier. The keyed free-text tier is also reachable from the ora CLI (ax deep-journey --task, v0.5+). Only publicly runnable agents are accepted (see GET /api/journey/agents). Unknown body fields are rejected (strict schema). Anonymous rate limits, three ways: a 20-per-minute burst cap per IP; a per-target cap of 100 runs per rolling 24h per (domain, intent, harness, model) - when a target is over the cap the response is HTTP 200 with the most recent stored run for that target (`rate_limited: true`) plus Retry-After, the freshness analog: a denied trigger still returns the newest result and consumes nothing; and a durable per-caller cap of 20 runs per rolling 24h per IP - exceeded, that one is a real 429 with `retry_after_ms` (there is no cached result to serve for a caller). On top of those, all anonymous callers together share a ceiling of 3000 runs per rolling 24h; when it is full every anonymous trigger gets the same 429 with `retry_after_ms` until the oldest run ages out, while keyed callers are unaffected. Keyed rate limit, one way: 1000 runs per rolling 24h per key, exhaustion being the same 429 with `retry_after_ms`. A keyed caller skips both the burst cap and the per-target cap - free text fragments the target key, so a per-target window over it could never fill. Successful and capped responses carry X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset headers describing exactly one window: the per-target window on an anonymous response, the per-key caller window on a keyed one. Note: journey insights use the 5-layer journey taxonomy (discovery, identity, access, payments, experience), deliberately distinct from the 4 scoring layers of the audit report (POST /api/scan) - never map between the two.
|
|
3070
3171
|
*/
|
|
3071
3172
|
createJourneyRun: {
|
|
3072
3173
|
requestBody: {
|
|
@@ -3129,7 +3230,7 @@ export interface operations {
|
|
|
3129
3230
|
"application/json": components["schemas"]["JourneyCappedRun"];
|
|
3130
3231
|
};
|
|
3131
3232
|
};
|
|
3132
|
-
/** @description Run created and dispatched. Open `stream_url` (SSE) to
|
|
3233
|
+
/** @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. */
|
|
3133
3234
|
201: {
|
|
3134
3235
|
headers: {
|
|
3135
3236
|
/** @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 */
|
|
@@ -3155,7 +3256,7 @@ export interface operations {
|
|
|
3155
3256
|
"application/json": components["schemas"]["ErrorResponse"];
|
|
3156
3257
|
};
|
|
3157
3258
|
};
|
|
3158
|
-
/** @description Caller limit exceeded - the 20-per-minute burst cap (anonymous callers only; a keyed caller skips it), or the durable per-caller budget (
|
|
3259
|
+
/** @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. */
|
|
3159
3260
|
429: {
|
|
3160
3261
|
headers: {
|
|
3161
3262
|
/** @description Seconds until next allowed request */
|
|
@@ -3219,7 +3320,7 @@ export interface operations {
|
|
|
3219
3320
|
"application/json": components["schemas"]["JourneyDomainRun"] | components["schemas"]["JourneyDomainRunGraph"];
|
|
3220
3321
|
};
|
|
3221
3322
|
};
|
|
3222
|
-
/** @description A new run was dispatched and is running (`dispatched` is true, no `result` yet). Open `stream_url`
|
|
3323
|
+
/** @description A new run was dispatched and is running (`dispatched` is true, no `result` yet). Open `stream_url` and hold it to its `result` or `error` frame: the stream is what saves the finished run, which a later call here or GET /api/journey/runs/{id} then reads. The record fields are identical across views, so this body is the same whichever view is in effect. */
|
|
3223
3324
|
201: {
|
|
3224
3325
|
content: {
|
|
3225
3326
|
"application/json": components["schemas"]["JourneyDomainRun"] | components["schemas"]["JourneyDomainRunGraph"];
|
|
@@ -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.30.0";
|