{ "openapi": "3.1.0", "info": { "title": "jitprompt API", "version": "0.1.0", "description": "Manage the documents in a namespace from scripts and CI. Authenticate with the same namespace API key your agents use for MCP: `Authorization: Bearer imcp_...`. The key decides the namespace; every route acts on it alone.\n\nGuides: https://docs.jitprompt.com" }, "paths": { "/documents": { "get": { "tags": [ "Documents" ], "summary": "List documents", "description": "Every document in the key's namespace, newest first, with its status.", "operationId": "listDocuments", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Document" }, "type": "array", "title": "Response Listdocuments" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "post": { "tags": [ "Documents" ], "summary": "Upload a document", "description": "Upload a Markdown, text, PDF or Word file as multipart form data\n(`file`, and optionally `title`). Ingestion starts at once; poll the\ndocument until its `status` is `ready` or `failed`. Identical content to a\ndocument already in the namespace returns that document with\n`deduped: true` and uses no ingestion. Counts against the plan's documents\nper namespace, ingestions per day and document size (402/413).", "operationId": "uploadDocument", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_uploadDocument" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Uploaded" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/documents/{document_id}": { "get": { "tags": [ "Documents" ], "summary": "Get a document", "description": "One document: title, source file name, status (`pending`, `parsing`,\n`structuring`, `embedding`, `ready`, `failed`), the error if it failed,\nits one-line summary and section count.", "operationId": "getDocument", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Documents" ], "summary": "Rename a document", "description": "Change the title. Does not re-ingest; `null` clears it.", "operationId": "renameDocument", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TitlePatch" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Documents" ], "summary": "Delete a document", "description": "Delete the document, its sections and its stored file. Agents stop\nseeing it immediately.", "operationId": "deleteDocument", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/reingest": { "post": { "tags": [ "Documents" ], "summary": "Re-ingest a document", "description": "Run ingestion again on the stored file \u2014 to retry a failure. Uses one\ningestion (a failure on our side gives it back).", "operationId": "reingestDocument", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/content": { "get": { "tags": [ "Documents" ], "summary": "Get a document's text", "description": "The document's text as the model structured it (for a PDF or Word file,\nthe extracted text), as `text/markdown`.", "operationId": "getDocumentContent", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Documents" ], "summary": "Replace a document's content", "description": "Replace the source and re-ingest. Send either multipart/form-data with a\n`file` field (a new filename is kept), or the raw text as the body with any\ntext/* content type (the filename stays).", "operationId": "replaceDocumentContent", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/sections": { "get": { "tags": [ "Documents" ], "summary": "List a document's sections", "description": "The sections the model made, in order: id, title, summary and token\ncount \u2014 and the full text with `content=true`. These are what agents read.", "operationId": "listSections", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } }, { "name": "content", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Content" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Section" }, "title": "Response Listsections" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/pins": { "get": { "tags": [ "Pinned documents" ], "summary": "List pinned documents", "description": "The pinned documents in order, each with its estimated tokens, and the\nblock's total against the namespace's cap. Every client agent gets the\npinned documents without asking: in the MCP `instructions`, or at the top\nof its first get_toc or search_instructions response. A document with\n`included: false` is pinned but left out \u2014 not ready yet, or past the cap\nsince an edit grew it.", "operationId": "listPins", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pins" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "put": { "tags": [ "Pinned documents" ], "summary": "Set the pinned documents", "description": "Replace the pinned list with these documents, in this order: ids (full\nor the 8-character prefix the tools show) or file names (`source_name`,\nwith or without the extension). An empty list unpins everything. 422 if\nthe block would pass the cap.", "operationId": "setPins", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinOrder" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pins" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/documents/{document_id}/pin": { "post": { "tags": [ "Pinned documents" ], "summary": "Pin a document", "description": "Pin one ready document, after those already pinned. 422 if the block\nwould pass the cap.", "operationId": "pinDocument", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pins" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Pinned documents" ], "summary": "Unpin a document", "description": "Unpin a document. Deleting a document unpins it too.", "operationId": "unpinDocument", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pins" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/pins/cap": { "put": { "tags": [ "Pinned documents" ], "summary": "Set the pinned-token cap", "description": "The most estimated tokens the pinned block may take, up to the\nserver's maximum; `null` for the default. 422 below what is pinned now.", "operationId": "setPinCap", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinCap" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pins" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/documents/{document_id}/versions": { "get": { "tags": [ "Versions" ], "summary": "List a document's versions", "description": "The kept versions of a document, newest (current) first. How many are\nkept depends on the plan (`features.versions_kept` in `GET /usage`).", "operationId": "listVersions", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Version" }, "title": "Response Listversions" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/versions/{version}/content": { "get": { "tags": [ "Versions" ], "summary": "Get a version's text", "description": "The text of one kept version (for a PDF or Word file, the extracted\ntext), as `text/markdown`.", "operationId": "getVersionContent", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "title": "Version" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/versions/{version}/restore": { "post": { "tags": [ "Versions" ], "summary": "Restore a version", "description": "Make a kept version the current content again and re-ingest it. Uses one\ningestion and records a new version, so the restore can be undone too.", "operationId": "restoreVersion", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "title": "Version" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/usage": { "get": { "tags": [ "Account" ], "summary": "Get plan and usage", "description": "The plan of the key's organization, its limits and what is used:\nnamespaces, documents per namespace, ingestions in the last 24 hours, and\nthis calendar month's ingestions, tokens and MCP calls.", "operationId": "getUsage", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/diagnostics": { "get": { "tags": [ "Account" ], "summary": "Get namespace diagnostics", "description": "The namespace's Diagnostics page as JSON. days: 1, 7 or 30.", "operationId": "getDiagnostics", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 7, "title": "Days" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "Body_uploadDocument": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "type": "object", "required": [ "file" ], "title": "Body_uploadDocument" }, "Document": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "namespace_id": { "type": "string", "format": "uuid", "title": "Namespace Id" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "source_name": { "type": "string", "title": "Source Name" }, "status": { "type": "string", "enum": [ "pending", "parsing", "structuring", "embedding", "ready", "failed" ], "title": "Status" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" }, "section_count": { "type": "integer", "title": "Section Count" } }, "type": "object", "required": [ "id", "namespace_id", "title", "summary", "source_name", "status", "error", "created_at", "updated_at", "section_count" ], "title": "Document" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "PinCap": { "properties": { "cap": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Cap" } }, "type": "object", "title": "PinCap" }, "PinOrder": { "properties": { "documents": { "items": { "type": "string" }, "type": "array", "title": "Documents" } }, "type": "object", "required": [ "documents" ], "title": "PinOrder" }, "PinnedDocument": { "properties": { "id": { "type": "string", "title": "Id" }, "title": { "type": "string", "title": "Title" }, "source_name": { "type": "string", "title": "Source Name" }, "status": { "type": "string", "title": "Status" }, "est_tokens": { "type": "integer", "title": "Est Tokens" }, "included": { "type": "boolean", "title": "Included" } }, "type": "object", "required": [ "id", "title", "source_name", "status", "est_tokens", "included" ], "title": "PinnedDocument" }, "Pins": { "properties": { "pins": { "items": { "$ref": "#/components/schemas/PinnedDocument" }, "type": "array", "title": "Pins" }, "total_tokens": { "type": "integer", "title": "Total Tokens" }, "cap": { "type": "integer", "title": "Cap" }, "max": { "type": "integer", "title": "Max" } }, "type": "object", "required": [ "pins", "total_tokens", "cap", "max" ], "title": "Pins" }, "Section": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "position": { "type": "integer", "title": "Position" }, "title": { "type": "string", "title": "Title" }, "summary": { "type": "string", "title": "Summary" }, "token_count": { "type": "integer", "title": "Token Count" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content" } }, "type": "object", "required": [ "id", "position", "title", "summary", "token_count" ], "title": "Section" }, "TitlePatch": { "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "type": "object", "title": "TitlePatch" }, "Uploaded": { "properties": { "document_id": { "type": "string", "format": "uuid", "title": "Document Id" }, "status": { "type": "string", "enum": [ "pending", "parsing", "structuring", "embedding", "ready", "failed" ], "title": "Status" }, "deduped": { "type": "boolean", "title": "Deduped" } }, "type": "object", "required": [ "document_id", "status", "deduped" ], "title": "Uploaded" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "Version": { "properties": { "version": { "type": "integer", "title": "Version" }, "source_name": { "type": "string", "title": "Source Name" }, "size_bytes": { "type": "integer", "title": "Size Bytes" }, "kind": { "type": "string", "enum": [ "upload", "replace", "restore", "baseline" ], "title": "Kind" }, "restored_from": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Restored From" }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "current": { "type": "boolean", "title": "Current" } }, "type": "object", "required": [ "version", "source_name", "size_bytes", "kind", "restored_from", "created_by", "created_at", "current" ], "title": "Version" } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer", "description": "A namespace API key (`imcp_...`), created on the namespace's API keys page." } } }, "servers": [ { "url": "https://app.jitprompt.com" } ] }