{ "components": { "schemas": { "Access": { "additionalProperties": false, "properties": { "rate_limit": { "$ref": "#/components/schemas/RateLimit" } }, "required": [ "rate_limit" ], "type": "object" }, "CaptureHistoryEntry": { "additionalProperties": false, "properties": { "capture_id": { "type": "string" }, "capture_time": { "type": "string" }, "content_digest": { "type": "string" }, "content_format": { "type": "string" } }, "required": [ "capture_id", "capture_time", "content_digest" ], "type": "object" }, "Citation": { "additionalProperties": false, "properties": { "index": { "format": "int64", "type": "integer" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "index", "title", "url" ], "type": "object" }, "ContentRange": { "additionalProperties": false, "properties": { "capture_id": { "description": "Optional capture pin; a stale_range warning is returned when the latest capture differs.", "type": "string" }, "max_chars": { "description": "Maximum characters for this range; overrides content.max_chars.", "format": "int64", "minimum": 1, "type": "integer" }, "start_char": { "description": "Character offset to start content from.", "format": "int64", "minimum": 0, "type": "integer" } }, "type": "object" }, "Document": { "additionalProperties": false, "properties": { "canonical_url": { "type": "string" }, "content_digest": { "type": "string" }, "doc_id": { "type": "string" }, "first_seen_at": { "type": "string" }, "headings": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "last_seen_at": { "type": "string" }, "latest_capture_id": { "type": "string" }, "meta_description": { "type": "string" }, "published_at": { "type": "string" }, "source_url": { "type": "string" }, "title": { "type": "string" } }, "required": [ "doc_id", "canonical_url", "source_url", "first_seen_at", "last_seen_at" ], "type": "object" }, "DocumentContent": { "additionalProperties": false, "properties": { "char_count": { "format": "int64", "type": "integer" }, "format": { "type": "string" }, "selection": { "type": "string" }, "start_char": { "format": "int64", "type": "integer" }, "text": { "type": "string" }, "truncated": { "type": "boolean" } }, "required": [ "selection", "format", "text", "truncated", "char_count" ], "type": "object" }, "DocumentContentRequest": { "additionalProperties": false, "properties": { "format": { "default": "markdown", "description": "Returned content format: markdown (default) preserves document structure (headings, lists, code blocks); text is plain text.", "enum": [ "text", "markdown" ], "type": "string" }, "include_offsets": { "description": "When true, passages carry char_start/char_end offsets into the full extracted text when available, for character-precise citation.", "type": "boolean" }, "max_chars": { "description": "Optional maximum content.text characters to return. Omit it for the full selected content. Longer capped reads set content.truncated true; continue with content.range.start_char instead of retrying with a larger cap.", "format": "int64", "minimum": 1, "type": "integer" }, "passage_ids": { "description": "Passage identifiers to return when selection is passage_ids, from a search result's passages or a previous read.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "range": { "$ref": "#/components/schemas/ContentRange", "description": "Continuation read: return content starting at a character offset of the same document." }, "selection": { "default": "full_document", "description": "How content.text is chosen: full_document (default) returns the extracted document text; query_relevant returns the passages most relevant to query; top_passages returns the document's leading passages; passage_ids returns exactly content.passage_ids; none returns no content body.", "enum": [ "none", "query_relevant", "top_passages", "passage_ids", "full_document" ], "type": "string" } }, "type": "object" }, "DocumentProvenance": { "additionalProperties": false, "properties": { "capture_id": { "type": "string" }, "capture_time": { "type": "string" } }, "required": [ "capture_id", "capture_time" ], "type": "object" }, "DocumentRequest": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/DocumentRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "canonical_url": { "description": "Canonical URL from a result's canonical_url; lookup alternative to doc_id. Either doc_id or canonical_url is required.", "format": "uri", "type": "string" }, "content": { "$ref": "#/components/schemas/DocumentContentRequest", "description": "Controls for returned document content: selection strategy, format, size cap, and continuation range." }, "debug": { "additionalProperties": {}, "description": "Reserved for internal evaluation harnesses; ignored for public callers.", "type": "object" }, "doc_id": { "description": "Canonical document identifier (UUID) from a search result's doc_id; stable across searches and recrawls. Either doc_id or canonical_url is required.", "examples": [ "0c944fa8-4c8f-4f48-9b08-0fb2fd3438ec" ], "format": "uuid", "type": "string" }, "include": { "description": "Sections to return. Omit it for everything available; otherwise an allowlist of passages, capture_history, and content (document metadata is always returned - send just metadata for a metadata-only read).", "items": { "enum": [ "metadata", "passages", "capture_history", "content" ], "type": "string" }, "type": [ "array", "null" ] }, "query": { "description": "Query context for passage selection when content.selection is query_relevant.", "type": "string" } }, "type": "object" }, "DocumentResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/DocumentResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "access": { "$ref": "#/components/schemas/Access" }, "capture_history": { "items": { "$ref": "#/components/schemas/CaptureHistoryEntry" }, "type": [ "array", "null" ] }, "content": { "$ref": "#/components/schemas/DocumentContent" }, "doc": { "$ref": "#/components/schemas/Document" }, "passages": { "items": { "$ref": "#/components/schemas/Passage" }, "type": [ "array", "null" ] }, "provenance": { "$ref": "#/components/schemas/DocumentProvenance" }, "request_id": { "type": "string" }, "session_id": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" }, "warnings": { "items": { "$ref": "#/components/schemas/Warning" }, "type": [ "array", "null" ] } }, "required": [ "request_id", "session_id", "access", "doc" ], "type": "object" }, "ErrorBody": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine-readable error code.", "type": "string" }, "details": { "additionalProperties": {}, "description": "Optional structured error details.", "type": "object" }, "message": { "description": "Human-readable error message.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "ErrorEnvelope": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/ErrorEnvelope.json" ], "format": "uri", "readOnly": true, "type": "string" }, "error": { "$ref": "#/components/schemas/ErrorBody", "description": "Error details." }, "request_id": { "description": "Server request identifier.", "type": "string" }, "type": { "description": "Envelope discriminator.", "enum": [ "error" ], "type": "string" } }, "required": [ "type", "request_id", "error" ], "type": "object" }, "FeedbackAgentContext": { "additionalProperties": false, "properties": { "client_model": { "description": "Calling model identifier.", "type": "string" }, "task_type": { "description": "Agent task type or evaluation bucket (e.g. 'coding' or 'research').", "type": "string" } }, "type": "object" }, "FeedbackRequest": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/FeedbackRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "agent_context": { "$ref": "#/components/schemas/FeedbackAgentContext", "description": "Optional calling-agent context for slicing feedback in evaluation." }, "doc_id": { "description": "Document the event concerns, from the result's doc_id.", "format": "uuid", "type": "string" }, "event_type": { "description": "What happened: result_helpful / result_not_helpful (the result did or did not advance the task), passage_used (a passage was used or cited), read_abandoned (opened but abandoned), duplicate_result, stale_result (outdated content), spam_or_low_quality, missing_expected_source (a source you expected did not appear), unsafe_or_policy_issue.", "enum": [ "result_helpful", "result_not_helpful", "passage_used", "read_abandoned", "duplicate_result", "stale_result", "spam_or_low_quality", "missing_expected_source", "unsafe_or_policy_issue" ], "type": "string" }, "notes": { "description": "Free-text context, recorded for human review and offline evaluation.", "type": "string" }, "passage_id": { "description": "Specific passage the event concerns, from passages[].passage_id; most useful with passage_used.", "format": "uuid", "type": "string" }, "query": { "description": "Query text the event relates to, useful when no search_id is available.", "type": "string" }, "rank": { "description": "One-based position the result had in the ranked list.", "format": "int64", "minimum": 1, "type": "integer" }, "search_id": { "description": "The search_id returned by /v1/search. Ties feedback to the exact ranked list that produced the result, so ranking learns from the right context.", "format": "uuid", "type": "string" }, "session_id": { "description": "Session the event belongs to (UUID), matching session_id from earlier responses.", "format": "uuid", "type": "string" } }, "required": [ "event_type" ], "type": "object" }, "FeedbackResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/FeedbackResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "accepted": { "type": "boolean" }, "access": { "$ref": "#/components/schemas/Access" }, "feedback_id": { "type": "string" }, "request_id": { "type": "string" }, "session_id": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } }, "required": [ "request_id", "feedback_id", "session_id", "access", "accepted" ], "type": "object" }, "FileDeleteResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/FileDeleteResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "deleted": { "description": "True when the file was removed.", "type": "boolean" } }, "required": [ "deleted" ], "type": "object" }, "FileIndexRequest": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/FileIndexRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "mode": { "description": "Indexing mode. incremental (default) processes new and changed files; full reprocesses everything.", "enum": [ "full", "incremental" ], "type": "string" } }, "type": "object" }, "FileIndexResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/FileIndexResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "state": { "description": "Initial run state.", "type": "string" }, "sync_id": { "description": "Identifier of the accepted indexing run; poll GET /v1/files/index/{sync_id}.", "type": "string" } }, "required": [ "sync_id", "state" ], "type": "object" }, "FileIndexStats": { "additionalProperties": false, "properties": { "bytes": { "description": "Bytes fetched.", "format": "int64", "type": "integer" }, "deleted": { "description": "Documents removed because the object is gone.", "format": "int64", "type": "integer" }, "enumerated": { "description": "Objects discovered.", "format": "int64", "type": "integer" }, "failed": { "description": "Objects that failed processing.", "format": "int64", "type": "integer" }, "fetched": { "description": "Objects downloaded for extraction.", "format": "int64", "type": "integer" }, "indexed": { "description": "Documents now searchable.", "format": "int64", "type": "integer" }, "skipped_unsupported": { "description": "Objects skipped as unsupported types.", "format": "int64", "type": "integer" } }, "required": [ "enumerated", "fetched", "indexed", "failed", "skipped_unsupported", "deleted", "bytes" ], "type": "object" }, "FileIndexStatusResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/FileIndexStatusResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "completed_at": { "description": "Run completion time (RFC 3339), null while in flight.", "type": [ "string", "null" ] }, "error": { "description": "Terminal error detail, null while healthy.", "type": [ "string", "null" ] }, "started_at": { "description": "Run start time (RFC 3339), null before it starts.", "type": [ "string", "null" ] }, "state": { "description": "Run state (queued, planning, running, completed, failed, …).", "type": "string" }, "stats": { "$ref": "#/components/schemas/FileIndexStats", "description": "Progress counters." }, "sync_id": { "description": "Indexing run identifier.", "type": "string" } }, "required": [ "sync_id", "state", "stats", "error", "started_at", "completed_at" ], "type": "object" }, "FileListResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/FileListResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "files": { "description": "The organization's uploaded files, newest first.", "items": { "$ref": "#/components/schemas/FileSummary" }, "type": [ "array", "null" ] } }, "required": [ "files" ], "type": "object" }, "FilePresignRequest": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/FilePresignRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "content_type": { "description": "Optional MIME type recorded on the object.", "maxLength": 255, "type": "string" }, "filename": { "description": "Filename to upload. Sanitized server-side; the response echoes the stored name.", "maxLength": 512, "minLength": 1, "type": "string" }, "size": { "description": "Exact file size in bytes. The presigned URL binds this length, so the PUT body must match it.", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "filename", "size" ], "type": "object" }, "FilePresignResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/FilePresignResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "expires_in_seconds": { "description": "Seconds until the presigned URL expires.", "format": "int64", "type": "integer" }, "max_object_bytes": { "description": "Per-file upload size limit in bytes.", "format": "int64", "type": "integer" }, "name": { "description": "Sanitized filename the upload will be stored and listed under.", "type": "string" }, "url": { "description": "Presigned S3 PUT URL. Upload the raw file bytes to this URL with an HTTP PUT (no Authorization header); the body must be exactly the declared size.", "type": "string" } }, "required": [ "url", "name", "expires_in_seconds", "max_object_bytes" ], "type": "object" }, "FileSummary": { "additionalProperties": false, "properties": { "last_modified": { "description": "Upload time (RFC 3339).", "type": "string" }, "name": { "description": "Filename.", "type": "string" }, "size": { "description": "Object size in bytes.", "format": "int64", "type": "integer" } }, "required": [ "name", "size" ], "type": "object" }, "IntegrationResultsResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/IntegrationResultsResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "access": { "$ref": "#/components/schemas/Access" }, "next_cursor": { "type": "string" }, "request_id": { "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/IntegrationSearchResult" }, "type": [ "array", "null" ] }, "search_id": { "type": "string" }, "total": { "format": "int64", "type": "integer" }, "usage": { "$ref": "#/components/schemas/Usage" } }, "required": [ "request_id", "search_id", "total", "results" ], "type": "object" }, "IntegrationResultsSummary": { "additionalProperties": false, "properties": { "href": { "type": "string" }, "selected": { "format": "int64", "type": "integer" }, "total": { "format": "int64", "type": "integer" } }, "required": [ "total", "selected", "href" ], "type": "object" }, "IntegrationSearchResult": { "additionalProperties": false, "properties": { "canonical_url": { "type": "string" }, "description": { "type": "string" }, "doc_id": { "type": "string" }, "index": { "type": "string" }, "integration": { "type": "string" }, "labels": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "metadata": { "$ref": "#/components/schemas/SearchResultMetadata" }, "mime": { "type": "string" }, "operation": { "type": "string" }, "passages": { "items": { "$ref": "#/components/schemas/Passage" }, "type": [ "array", "null" ] }, "primary_rank": { "format": "int64", "type": "integer" }, "provenance": { "$ref": "#/components/schemas/DocumentProvenance" }, "rank": { "format": "int64", "type": "integer" }, "score": { "$ref": "#/components/schemas/SearchScore" }, "selected": { "type": "boolean" }, "snippet": { "type": "string" }, "source_uri": { "type": "string" }, "source_url": { "type": "string" }, "title": { "type": "string" } }, "required": [ "integration", "operation", "selected", "rank", "doc_id", "canonical_url" ], "type": "object" }, "Passage": { "additionalProperties": false, "properties": { "char_end": { "format": "int64", "type": "integer" }, "char_start": { "format": "int64", "type": "integer" }, "doc_id": { "type": "string" }, "ordinal": { "format": "int64", "type": "integer" }, "passage_id": { "type": "string" }, "section_heading": { "type": "string" }, "section_path": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "text": { "type": "string" } }, "required": [ "passage_id", "doc_id", "ordinal", "text" ], "type": "object" }, "Ranking": { "additionalProperties": false, "properties": { "ranker_version": { "type": "string" }, "score_scope": { "type": "string" } }, "required": [ "ranker_version", "score_scope" ], "type": "object" }, "RateLimit": { "additionalProperties": false, "properties": { "limit_rps": { "format": "int64", "type": "integer" }, "remaining": { "format": "int64", "type": "integer" }, "reset_at": { "type": "string" } }, "required": [ "limit_rps", "remaining", "reset_at" ], "type": "object" }, "ResearchJobResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/ResearchJobResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "access": { "$ref": "#/components/schemas/Access" }, "completed_at": { "type": "string" }, "created_at": { "type": "string" }, "error": { "description": "Present when status is failed.", "type": "string" }, "id": { "type": "string" }, "request_id": { "type": "string" }, "result": { "$ref": "#/components/schemas/ResearchResultResponse", "description": "Present when status is completed." }, "status": { "description": "queued, running, completed, or failed.", "type": "string" } }, "required": [ "request_id", "id", "status", "created_at" ], "type": "object" }, "ResearchJobSummary": { "additionalProperties": false, "properties": { "completed_at": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "string" }, "query": { "type": "string" }, "status": { "description": "queued, running, completed, or failed.", "type": "string" } }, "required": [ "id", "status", "query", "created_at" ], "type": "object" }, "ResearchListResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/ResearchListResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "access": { "$ref": "#/components/schemas/Access" }, "jobs": { "items": { "$ref": "#/components/schemas/ResearchJobSummary" }, "type": [ "array", "null" ] }, "request_id": { "type": "string" } }, "required": [ "request_id", "jobs" ], "type": "object" }, "ResearchRequest": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/ResearchRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "excluded_domains": { "description": "Domains to drop from results.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "max_tool_calls": { "description": "Max tool calls (web_search/web_read/scratchpad) before a final answer is forced. Optional; defaults internally. The agent usually stops earlier on its own.", "format": "int64", "type": "integer" }, "query": { "description": "Research question to investigate.", "type": "string" }, "source_timeout": { "description": "Per-source fetch timeout in seconds.", "format": "int64", "type": "integer" } }, "required": [ "query" ], "type": "object" }, "ResearchResultResponse": { "additionalProperties": false, "properties": { "citations": { "items": { "$ref": "#/components/schemas/Citation" }, "type": [ "array", "null" ] }, "confidence": { "type": "string" }, "content": { "type": "string" }, "failure_tool": { "type": "string" }, "failure_turn": { "format": "int64", "type": "integer" }, "llm_calls": { "format": "int64", "type": "integer" }, "query": { "type": "string" }, "read_count": { "format": "int64", "type": "integer" }, "run_id": { "type": "string" }, "tool_calls_used": { "format": "int64", "type": "integer" }, "tool_invocations": { "items": { "$ref": "#/components/schemas/ToolInvocation" }, "type": [ "array", "null" ] } }, "required": [ "content", "query", "citations", "read_count", "confidence", "tool_calls_used", "llm_calls" ], "type": "object" }, "ResearchStartResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/ResearchStartResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "access": { "$ref": "#/components/schemas/Access" }, "id": { "description": "Job id to poll at GET /v1/research/{id}.", "type": "string" }, "request_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "request_id", "id", "status" ], "type": "object" }, "ResponseBudget": { "additionalProperties": false, "properties": { "max_chars_total": { "description": "Maximum serialized response size in characters (roughly 4 characters per token, so 2000 is about 500 tokens).", "format": "int64", "minimum": 1, "type": "integer" }, "on_exceed": { "default": "shed", "description": "What to do when the budget binds: shed (default) trims in a fixed order - passages, snippet tails, preset extras, then tail results, never below one result - and sets truncated plus a response_truncated warning; error fails with response_too_large instead.", "enum": [ "shed", "error" ], "type": "string" } }, "type": "object" }, "ResponseShape": { "additionalProperties": false, "properties": { "budget": { "$ref": "#/components/schemas/ResponseBudget", "description": "Total serialized response budget in characters with deterministic shedding." }, "verbosity": { "default": "standard", "description": "Field preset: ids_only (rank, doc_id, url, title), compact (adds snippet, score, key dates), standard (today's default), full (adds provenance).", "enum": [ "ids_only", "compact", "standard", "full" ], "type": "string" } }, "type": "object" }, "SearchRequest": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/SearchRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "client_model": { "description": "Calling model identifier, recorded for analytics and ranking tuning.", "type": "string" }, "filters": { "additionalProperties": {}, "description": "Structured filters. Keys: country (two-letter code such as 'us' or 'de', scoping results to a market), language (two-letter code such as 'en'), exact_match (boolean; quotes the query so the index matches it verbatim).", "type": "object" }, "freshness_policy": { "additionalProperties": {}, "description": "Recency requirements. Keys: published_after (RFC 3339 timestamp or YYYY-MM-DD date; only content published after it) and freshness (coarse window code pd, pw, pm, or py for past day, week, month, or year; ignored when published_after is set).", "type": "object" }, "max_results": { "default": 10, "description": "Maximum number of ranked results to return. The response carries fewer when the index has fewer matches.", "format": "int64", "maximum": 50, "minimum": 1, "type": "integer" }, "query": { "description": "The search query, phrased as the user or agent would ask it. Drives ranking and passage selection even when search_queries supplies a rewrite.", "examples": [ "linux kernel amd gpu suspend" ], "minLength": 1, "type": "string" }, "response": { "$ref": "#/components/schemas/ResponseShape", "description": "Optional response shaping: verbosity preset and serialized-size budget." }, "scope": { "$ref": "#/components/schemas/SearchScope", "description": "Which indexes to search. Omit it for the web index. Additive: existing clients are unaffected." }, "search_queries": { "description": "Caller-provided query rewrites. The first entry replaces query as the text sent to the search index; query still drives reranking and passage selection. All entries are visible to the server-side query rewriter.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "session_id": { "description": "Client session identifier (UUID). Groups related search, document, and feedback calls; equivalent to the X-Session-ID header. When omitted, the server generates one and echoes it back as session_id.", "format": "uuid", "type": "string" }, "source_policy": { "additionalProperties": {}, "description": "Domain allow/deny policy. Keys: include_domains (array of domains; with require_domain_match true, results outside them are dropped, and a single entry is also sent to the index as a site: operator), exclude_domains (array of domains whose results are always dropped), require_domain_match (boolean). Domains match their subdomains; a leading www. is ignored.", "type": "object" } }, "required": [ "query" ], "type": "object" }, "SearchResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/SearchResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "access": { "$ref": "#/components/schemas/Access" }, "integration_results": { "$ref": "#/components/schemas/IntegrationResultsSummary" }, "ranking": { "$ref": "#/components/schemas/Ranking" }, "request_id": { "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/SearchResult" }, "type": [ "array", "null" ] }, "search_id": { "type": "string" }, "session_id": { "type": "string" }, "truncated": { "type": "boolean" }, "usage": { "$ref": "#/components/schemas/Usage" }, "warnings": { "items": { "$ref": "#/components/schemas/Warning" }, "type": [ "array", "null" ] } }, "required": [ "request_id", "search_id", "session_id", "results" ], "type": "object" }, "SearchResult": { "additionalProperties": false, "properties": { "canonical_url": { "type": "string" }, "description": { "type": "string" }, "doc_id": { "type": "string" }, "index": { "type": "string" }, "labels": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "metadata": { "$ref": "#/components/schemas/SearchResultMetadata" }, "mime": { "type": "string" }, "passages": { "items": { "$ref": "#/components/schemas/Passage" }, "type": [ "array", "null" ] }, "provenance": { "$ref": "#/components/schemas/DocumentProvenance" }, "rank": { "format": "int64", "type": "integer" }, "score": { "$ref": "#/components/schemas/SearchScore" }, "snippet": { "type": "string" }, "source_uri": { "type": "string" }, "source_url": { "type": "string" }, "title": { "type": "string" } }, "required": [ "rank", "doc_id", "canonical_url" ], "type": "object" }, "SearchResultMetadata": { "additionalProperties": false, "properties": { "content_digest": { "type": "string" }, "extracted_at": { "type": "string" }, "first_seen_at": { "type": "string" }, "last_crawled_at": { "type": "string" }, "last_seen_at": { "type": "string" }, "published_at": { "type": "string" } }, "type": "object" }, "SearchScope": { "additionalProperties": false, "properties": { "indexes": { "description": "Indexes to search: web (the shared web corpus) and/or workspace (your organization's ingested documents). Default: [\"web\"].", "items": { "type": "string" }, "type": [ "array", "null" ] }, "workspace_id": { "description": "Workspace to search; required when indexes includes workspace.", "format": "uuid", "type": "string" } }, "type": "object" }, "SearchScore": { "additionalProperties": false, "properties": { "value": { "format": "double", "type": "number" } }, "required": [ "value" ], "type": "object" }, "ToolInvocation": { "additionalProperties": false, "properties": { "error": { "type": "string" }, "latency_ms": { "format": "int64", "type": "integer" }, "ordinal": { "format": "int64", "type": "integer" }, "query": { "type": "string" }, "result_count": { "format": "int64", "type": "integer" }, "status": { "type": "string" }, "tool": { "type": "string" }, "turn": { "format": "int64", "type": "integer" }, "url": { "type": "string" } }, "required": [ "ordinal", "turn", "tool", "status", "result_count", "latency_ms" ], "type": "object" }, "Usage": { "additionalProperties": false, "properties": { "bytes_returned": { "format": "int64", "type": "integer" }, "requests": { "format": "int64", "type": "integer" } }, "required": [ "requests", "bytes_returned" ], "type": "object" }, "UsageEndpointSummary": { "additionalProperties": false, "properties": { "errors": { "description": "4xx/5xx responses on this route.", "format": "int64", "type": "integer" }, "label": { "description": "Human label for known routes; raw route otherwise.", "type": "string" }, "p95_duration_ms": { "description": "95th-percentile duration on this route.", "format": "double", "type": "number" }, "requests": { "description": "Requests to this route.", "format": "int64", "type": "integer" }, "route": { "description": "Public API route, e.g. /v1/search.", "type": "string" } }, "required": [ "route", "label", "requests", "errors", "p95_duration_ms" ], "type": "object" }, "UsageHeadline": { "additionalProperties": false, "properties": { "avg_duration_ms": { "description": "Mean request duration.", "format": "double", "type": "number" }, "error_rate": { "description": "errors / requests; 0 when there are no requests.", "format": "double", "type": "number" }, "errors": { "description": "Requests that answered 4xx or 5xx.", "format": "int64", "type": "integer" }, "p95_duration_ms": { "description": "95th-percentile request duration.", "format": "double", "type": "number" }, "requests": { "description": "Total API requests in the window.", "format": "int64", "type": "integer" }, "spend_cents": { "description": "Billable platform spend in exact (possibly fractional) cents.", "format": "double", "type": "number" } }, "required": [ "requests", "errors", "error_rate", "avg_duration_ms", "p95_duration_ms", "spend_cents" ], "type": "object" }, "UsageKeySummary": { "additionalProperties": false, "properties": { "api_key_id": { "description": "API key identifier.", "type": "string" }, "errors": { "description": "4xx/5xx responses attributed to this key.", "format": "int64", "type": "integer" }, "key_prefix": { "description": "Public key prefix (never the secret).", "type": "string" }, "last_used_at": { "description": "Most recent request time (RFC 3339).", "type": "string" }, "name": { "description": "Key name; deleted keys are suffixed \"(deleted)\".", "type": "string" }, "p95_duration_ms": { "description": "95th-percentile duration for this key.", "format": "double", "type": "number" }, "requests": { "description": "Requests attributed to this key.", "format": "int64", "type": "integer" }, "spend_cents": { "description": "Billable spend attributed to this key, exact cents.", "format": "double", "type": "number" }, "status": { "description": "Key lifecycle state.", "enum": [ "active", "deleted" ], "type": "string" } }, "required": [ "api_key_id", "name", "key_prefix", "status", "requests", "errors", "p95_duration_ms", "last_used_at", "spend_cents" ], "type": "object" }, "UsageLatencyPoint": { "additionalProperties": false, "properties": { "avg_duration_ms": { "description": "Mean request duration in this bucket.", "format": "double", "type": "number" }, "bucket": { "description": "Bucket start (RFC 3339, UTC-aligned).", "type": "string" }, "p95_duration_ms": { "description": "95th-percentile duration in this bucket.", "format": "double", "type": "number" } }, "required": [ "bucket", "avg_duration_ms", "p95_duration_ms" ], "type": "object" }, "UsageOverviewResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://alpha.api.trycaesar.com/UsageOverviewResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "endpoints": { "description": "Per-route breakdown, requests desc.", "items": { "$ref": "#/components/schemas/UsageEndpointSummary" }, "type": [ "array", "null" ] }, "headline": { "$ref": "#/components/schemas/UsageHeadline", "description": "Window totals." }, "keys": { "description": "Per-API-key breakdown, requests desc.", "items": { "$ref": "#/components/schemas/UsageKeySummary" }, "type": [ "array", "null" ] }, "latency_series": { "description": "Latency per bucket, ungrouped.", "items": { "$ref": "#/components/schemas/UsageLatencyPoint" }, "type": [ "array", "null" ] }, "products": { "description": "Billable products and spend.", "items": { "$ref": "#/components/schemas/UsageProductSummary" }, "type": [ "array", "null" ] }, "range": { "$ref": "#/components/schemas/UsageRange", "description": "The resolved query window." }, "series": { "description": "Requests per bucket, zero-filled.", "items": { "$ref": "#/components/schemas/UsageSeriesPoint" }, "type": [ "array", "null" ] } }, "required": [ "range", "headline", "series", "latency_series", "keys", "endpoints", "products" ], "type": "object" }, "UsageProductSummary": { "additionalProperties": false, "properties": { "label": { "description": "Human product label.", "type": "string" }, "product": { "description": "Billable product identifier (web_search, document_get, research).", "type": "string" }, "requests": { "description": "Metered billable count.", "format": "int64", "type": "integer" }, "spend_cents": { "description": "Spend for this product in the window.", "format": "double", "type": "number" } }, "required": [ "product", "label", "requests", "spend_cents" ], "type": "object" }, "UsageRange": { "additionalProperties": false, "properties": { "from": { "description": "Window start (RFC 3339, inclusive).", "type": "string" }, "interval": { "description": "Bucket size of the series.", "enum": [ "hour", "day" ], "type": "string" }, "timezone": { "description": "Always UTC.", "type": "string" }, "to": { "description": "Window end (RFC 3339, exclusive).", "type": "string" } }, "required": [ "from", "to", "interval", "timezone" ], "type": "object" }, "UsageSeriesPoint": { "additionalProperties": false, "properties": { "bucket": { "description": "Bucket start (RFC 3339, UTC-aligned).", "type": "string" }, "errors": { "description": "4xx/5xx responses in this bucket.", "format": "int64", "type": "integer" }, "group_id": { "description": "Group identifier when the series is grouped, null otherwise.", "type": [ "string", "null" ] }, "group_label": { "description": "Human label for the group, null when ungrouped.", "type": [ "string", "null" ] }, "requests": { "description": "Requests in this bucket.", "format": "int64", "type": "integer" } }, "required": [ "bucket", "group_id", "group_label", "requests", "errors" ], "type": "object" }, "Warning": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "securitySchemes": { "bearerApiKey": { "bearerFormat": "API key", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Local implementation of the v1 search, document, feedback, and internal operational APIs.", "title": "Agent Search API (Public)", "version": "0.1.0" }, "openapi": "3.1.0", "paths": { "/v1/document": { "post": { "description": "Inspect one canonical document and retrieve selected content.", "operationId": "get-document", "parameters": [ { "description": "Optional client session identifier.", "in": "header", "name": "X-Session-ID", "schema": { "description": "Optional client session identifier.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } }, "description": "Document payload." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation error." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid API key." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Insufficient prepaid balance." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "API key does not have the required scope." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Document not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal error." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Search infrastructure unreachable." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Search infrastructure unavailable." } }, "security": [ { "bearerApiKey": [] } ], "summary": "Get a document", "tags": [ "Documents" ], "x-audience": "public" } }, "/v1/feedback": { "post": { "description": "Persist an agent or evaluation feedback event.", "operationId": "record-feedback", "parameters": [ { "description": "Optional client session identifier.", "in": "header", "name": "X-Session-ID", "schema": { "description": "Optional client session identifier.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackResponse" } } }, "description": "Feedback accepted." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation error." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid API key." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "API key does not have the required scope." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Search or document target not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal error." } }, "security": [ { "bearerApiKey": [] } ], "summary": "Record feedback", "tags": [ "Feedback" ], "x-audience": "public" } }, "/v1/files": { "get": { "description": "List the organization's uploaded files in its Files knowledge base.", "operationId": "list-files", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileListResponse" } } }, "description": "Uploaded files." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid API key." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "API key does not have the required scope." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "File service unreachable." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "File endpoints are not configured." } }, "security": [ { "bearerApiKey": [] } ], "summary": "List uploaded files", "tags": [ "Files" ], "x-audience": "public" } }, "/v1/files/index": { "post": { "description": "Start an indexing run over the organization's uploaded files so they become searchable in the workspace index. Poll GET /v1/files/index/{sync_id} for progress.", "operationId": "index-files", "parameters": [ { "description": "Optional client session identifier.", "in": "header", "name": "X-Session-ID", "schema": { "description": "Optional client session identifier.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileIndexRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileIndexResponse" } } }, "description": "Indexing run accepted." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation error." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid API key." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "API key does not have the required scope." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "File service unreachable." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "File endpoints or indexing are not configured." } }, "security": [ { "bearerApiKey": [] } ], "summary": "Index uploaded files", "tags": [ "Files" ], "x-audience": "public" } }, "/v1/files/index/{sync_id}": { "get": { "description": "Progress and outcome of one files indexing run.", "operationId": "get-files-index-status", "parameters": [ { "description": "Indexing run identifier returned by POST /v1/files/index.", "in": "path", "name": "sync_id", "required": true, "schema": { "description": "Indexing run identifier returned by POST /v1/files/index.", "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileIndexStatusResponse" } } }, "description": "Indexing run status." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid API key." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "API key does not have the required scope." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Indexing run not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "File service unreachable." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "File endpoints are not configured." } }, "security": [ { "bearerApiKey": [] } ], "summary": "Get indexing run status", "tags": [ "Files" ], "x-audience": "public" } }, "/v1/files/presign": { "post": { "description": "Create a presigned S3 PUT URL for one file. Upload the raw bytes to the returned url with an HTTP PUT and no Authorization header; the body must be exactly the declared size. Then trigger POST /v1/files/index to make the file searchable via /v1/search with scope.indexes [\"workspace\"].", "operationId": "presign-file-upload", "parameters": [ { "description": "Optional client session identifier.", "in": "header", "name": "X-Session-ID", "schema": { "description": "Optional client session identifier.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilePresignRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilePresignResponse" } } }, "description": "Presigned upload URL." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation error." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid API key." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "API key does not have the required scope." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "File exceeds the size limit." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unsupported file type." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "File service unreachable." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "File endpoints are not configured." } }, "security": [ { "bearerApiKey": [] } ], "summary": "Create a presigned upload URL", "tags": [ "Files" ], "x-audience": "public" } }, "/v1/files/{name}": { "delete": { "description": "Delete one uploaded file by name. The document drops out of workspace search after the next indexing run (one is triggered automatically).", "operationId": "delete-file", "parameters": [ { "description": "Filename to delete, as returned by GET /v1/files.", "in": "path", "name": "name", "required": true, "schema": { "description": "Filename to delete, as returned by GET /v1/files.", "maxLength": 512, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDeleteResponse" } } }, "description": "File deleted." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation error." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid API key." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "API key does not have the required scope." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "File service unreachable." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "File endpoints are not configured." } }, "security": [ { "bearerApiKey": [] } ], "summary": "Delete an uploaded file", "tags": [ "Files" ], "x-audience": "public" } }, "/v1/research": { "get": { "description": "Return the caller's research jobs, most recent first. Lightweight: result bodies are omitted (fetch a job by id for its result).", "operationId": "list-research", "parameters": [ { "description": "Max jobs to return (default 50, max 200).", "explode": false, "in": "query", "name": "limit", "schema": { "description": "Max jobs to return (default 50, max 200).", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchListResponse" } } }, "description": "Research jobs." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid API key, or missing API key when keyless access is disabled." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited." } }, "security": [ { "bearerApiKey": [] } ], "summary": "List the caller's research runs", "tags": [ "Research" ], "x-audience": "public" }, "post": { "description": "Kick off an asynchronous deep-research run and return a job id to poll.", "operationId": "start-research", "parameters": [ { "description": "Optional client session identifier.", "in": "header", "name": "X-Session-ID", "schema": { "description": "Optional client session identifier.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchStartResponse" } } }, "description": "Research run accepted." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation error." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid API key, or missing API key when keyless access is disabled." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Insufficient prepaid balance." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "API key does not have the required scope." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited, or too many concurrent research jobs." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal error." } }, "security": [ { "bearerApiKey": [] } ], "summary": "Start a research run", "tags": [ "Research" ], "x-audience": "public" } }, "/v1/research/{id}": { "get": { "description": "Poll a research job; returns its status, plus the result when completed or the error when failed.", "operationId": "get-research", "parameters": [ { "description": "Research job id.", "in": "path", "name": "id", "required": true, "schema": { "description": "Research job id.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchJobResponse" } } }, "description": "Research job status." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid API key, or missing API key when keyless access is disabled." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Research job not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited." } }, "security": [ { "bearerApiKey": [] } ], "summary": "Get a research run's status and result", "tags": [ "Research" ], "x-audience": "public" } }, "/v1/search": { "post": { "description": "Run ranked retrieval over canonical documents and passages.", "operationId": "search", "parameters": [ { "description": "Optional client session identifier.", "in": "header", "name": "X-Session-ID", "schema": { "description": "Optional client session identifier.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } }, "description": "Search results." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation error." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid API key." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Insufficient prepaid balance." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "API key does not have the required scope." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal error." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Search infrastructure unreachable." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Search infrastructure unavailable." } }, "security": [ { "bearerApiKey": [] } ], "summary": "Search", "tags": [ "Search" ], "x-audience": "public" } }, "/v1/search/{search_id}/integration-results": { "get": { "description": "Retrieve integration records already acquired during a search without invoking providers again.", "operationId": "get-search-integration-results", "parameters": [ { "description": "Search identifier returned by POST /v1/search.", "in": "path", "name": "search_id", "required": true, "schema": { "description": "Search identifier returned by POST /v1/search.", "type": "string" } }, { "description": "Maximum results in this page.", "explode": false, "in": "query", "name": "limit", "schema": { "default": 20, "description": "Maximum results in this page.", "format": "int64", "maximum": 50, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor returned by the previous page.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque cursor returned by the previous page.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationResultsResponse" } } }, "description": "Stored integration results." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid limit or cursor." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid API key." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "API key does not have the required scope." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Search not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Stored integration results are unavailable." } }, "security": [ { "bearerApiKey": [] } ], "summary": "Get stored integration results", "tags": [ "Search" ], "x-audience": "public" } }, "/v1/usage": { "get": { "description": "Usage analytics for the API key's organization: request and error totals, latency, per-key and per-endpoint breakdowns, and billable product spend. Defaults to the last 30 days in day buckets (UTC).", "operationId": "get-usage", "parameters": [ { "description": "Window start (ISO 8601). Default: 30 days before to.", "explode": false, "in": "query", "name": "from", "schema": { "description": "Window start (ISO 8601). Default: 30 days before to.", "type": "string" } }, { "description": "Window end (ISO 8601). Default: now.", "explode": false, "in": "query", "name": "to", "schema": { "description": "Window end (ISO 8601). Default: now.", "type": "string" } }, { "description": "Bucket size for the series. Default day; hour requires a range of at most 8 days.", "explode": false, "in": "query", "name": "interval", "schema": { "description": "Bucket size for the series. Default day; hour requires a range of at most 8 days.", "enum": [ "", "hour", "day" ], "type": "string" } }, { "description": "Comma-separated API key uuids to filter by (at most 50).", "explode": false, "in": "query", "name": "api_key_ids", "schema": { "description": "Comma-separated API key uuids to filter by (at most 50).", "type": "string" } }, { "description": "Optional grouping of the request series.", "explode": false, "in": "query", "name": "group_by", "schema": { "description": "Optional grouping of the request series.", "enum": [ "", "none", "api_key", "endpoint", "status_class" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageOverviewResponse" } } }, "description": "Organization usage overview." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid range or filter." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid API key." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "API key does not have the required scope." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Usage service unreachable." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Usage endpoint is not configured." } }, "security": [ { "bearerApiKey": [] } ], "summary": "Get organization usage", "tags": [ "Usage" ], "x-audience": "public" } } }, "servers": [ { "description": "Staging", "url": "https://alpha.api.trycaesar.com" }, { "description": "Local development", "url": "http://localhost:8080" } ], "tags": [ { "description": "Public search APIs.", "name": "Search" }, { "description": "Public document inspection APIs.", "name": "Documents" }, { "description": "Public feedback ingestion APIs.", "name": "Feedback" }, { "description": "Asynchronous deep-research APIs.", "name": "Research" }, { "description": "Internal health, readiness, and metrics APIs.", "name": "Operations" } ] }