{ "components": { "securitySchemes": { "apiKey": { "description": "Account-level Atlas API key (rlka_...), created in the Atlas app. The plaintext is shown exactly once at mint.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "The Atlas public API — a versioned projection of the User Action catalog. One source generates the in-app UI, the Fleet agent abilities, the MCP tools, and this API, so they never drift. Authenticate with an account-level API key (Authorization: Bearer rlka_...) minted in the Atlas app; every request names its target project and is authorized by the key owner's live access level there. Endpoint families carry three-part versions; an endpoint retires only on a published notice of at least 30 days. Human-readable docs: https://runlog.ai/docs", "title": "Atlas API", "version": "1.0.0" }, "openapi": "3.0.3", "paths": { "/v1/api/actions": { "post": { "description": "Dispatches one User Action against the project named by the X-Project-Id header. The key owner's access level on that project authorizes the call — a project the owner is not a member of answers 404, and a key whose owner holds view-only access there dispatches read actions only. Rate limit: 60 requests per minute per key.", "operationId": "dispatchAction", "parameters": [ { "description": "The target project's id. Also accepted as the projectId query parameter.", "in": "header", "name": "X-Project-Id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "description": "Generate or revise a structured artifact (report, memo, summary) built from the project's corpus. Contract: Generation is detached: a dispatch returns the running task to poll, and a dispatch naming an artifactId is refused on the API surface today — omit it to generate a new artifact.", "properties": { "action": { "enum": [ "artifact_update" ], "type": "string" }, "input": { "additionalProperties": false, "properties": { "artifactId": { "description": "existing artifact id to update; omit to generate a new one", "type": "string" }, "purpose": { "description": "what the artifact should produce", "type": "string" } }, "required": [ "purpose" ], "type": "object" } }, "required": [ "action", "input" ], "title": "artifact_update (artifact v1.0.0)", "type": "object" }, { "description": "Return the slice of an ingested repository one coding task needs: the declarations ranked most relevant to the task, each as a signature citing its file and line, packed to a token budget. Complements an exact-string search rather than replacing it — it answers which code to read, not what it says. Contract: The response is signatures, never bodies: each declaration carries its header, file, and line span so you read the source yourself at the cited position. Contract: The pack is ranked for precision, not coverage — it returns the few declarations a task turns on and stops well short of the budget when nothing else scores. A short pack is an answer, not a truncation; re-dispatch with a sharper task rather than a larger budget. Contract: Seeds are subtracted from the answer: anything you name in seedSymbols or seedFiles steers the ranking and is never spent on your budget.", "properties": { "action": { "enum": [ "code_context_pack" ], "type": "string" }, "input": { "additionalProperties": false, "properties": { "budget": { "description": "approximate token ceiling the pack fills (default 4096)", "type": "number" }, "seedFiles": { "description": "file paths already open in your context, comma- or newline-separated; same effect as seed symbols", "type": "string" }, "seedSymbols": { "description": "declarations already in your context, comma- or newline-separated; they steer the ranking and are never returned back to you", "type": "string" }, "task": { "description": "the coding task in prose — what is being changed, in the words the codebase itself uses", "type": "string" } }, "required": [ "task" ], "type": "object" } }, "required": [ "action", "input" ], "title": "code_context_pack (code v1.0.0)", "type": "object" }, { "description": "List the ingested code units whose symbol name matches a typed prefix, each as an addressable reference — a stable symbol id, the symbol name as its label, and its file path as its sublabel. This is the manual override for retrieval: what a mention picker loads so a user can point at code by name. Contract: References are a bounded page ordered prefix-matches-first, then substring matches, each alphabetical, so the list stays stable as the user keeps typing. Contract: The symbol id is stable across re-ingests — store that, never the label, when persisting what a user picked.", "properties": { "action": { "enum": [ "code_references" ], "type": "string" }, "input": { "additionalProperties": false, "properties": { "query": { "description": "the prefix typed so far; empty lists the first page alphabetically", "type": "string" } }, "type": "object" } }, "required": [ "action", "input" ], "title": "code_references (code v1.0.0)", "type": "object" }, { "description": "Pull a document into the project's corpus so its factions, cells, and entities feed the memory graph. Contract: Dispatch only starts the ingestion: the source ingests on a detached task the response names, so poll that task rather than treating the dispatch as a completed ingest.", "properties": { "action": { "enum": [ "document_ingest" ], "type": "string" }, "input": { "additionalProperties": false, "properties": { "source": { "description": "document url or file reference to ingest", "type": "string" } }, "required": [ "source" ], "type": "object" } }, "required": [ "action", "input" ], "title": "document_ingest (document v1.0.0)", "type": "object" }, { "description": "Read the project's Atlas memory. With a query, returns the cells, entities, and artifacts ranked relevant to it, each carrying its ids as provenance; without one, lists cells (units of knowledge) or entities as a windowed dump. Scoped to the project the connection is bound to. Contract: List reads are windowed: a dispatch returns one bounded page of items plus a nextCursor; pass the returned cursor to continue and treat an empty nextCursor as the final page — a single dispatch is never the whole memory. Contract: Query reads are budgeted, not paged: the response packs the most relevant cells, entities, and artifacts into the requested token budget and stops — dispatch again with a refined query rather than a cursor.", "properties": { "action": { "enum": [ "memory_query" ], "type": "string" }, "input": { "additionalProperties": false, "properties": { "budget": { "description": "query mode: approximate token ceiling the ranked response packs to (default 4096)", "type": "number" }, "cursor": { "description": "list mode: the nextCursor from a prior dispatch, to continue the window", "type": "string" }, "kind": { "description": "list mode: what to read — 'cells' (default) or 'entities'", "type": "string" }, "query": { "description": "natural-language question or task; when present, results come ranked by relevance to it instead of as a paged dump", "type": "string" } }, "type": "object" } }, "required": [ "action", "input" ], "title": "memory_query (memory v1.0.0)", "type": "object" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "description": "the dispatched action id", "type": "string" }, "result": { "description": "the action's result payload" } }, "required": [ "action", "result" ], "type": "object" } } }, "description": "The dispatch result." }, "400": { "description": "Missing project header, action, or malformed body." }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "The action is not available to an API key, or not to this key's owner at their access level on the project." }, "404": { "description": "Unknown action, or a project the key's owner is not a member of." }, "429": { "description": "Rate limit exceeded (60 requests per minute per key)." } }, "summary": "Dispatch a catalog action against a project" } } }, "security": [ { "apiKey": [] } ], "servers": [ { "url": "https://relay.runlogai.com" } ] }