{"openapi":"3.1.0","info":{"title":"AxiomAI Public API","version":"1.1.0","summary":"Programmatic access to your hired AxiomAI employees.","description":"Programmatic access to your hired AxiomAI employees: list hires, run chats, queue background tasks, read usage and documents. All endpoints require a Bearer API key (`Authorization: Bearer mi_live_…`). Per-key rate limits are reported via `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers; `429` responses additionally include a `Retry-After` header.","contact":{"name":"Mahlum Innovations","email":"colter@mahluminnovations.com"},"license":{"name":"Proprietary"}},"servers":[{"url":"/api/v1","description":"Same-origin v1 API"}],"tags":[{"name":"Hires","description":"Active AI employee hires for the API key owner."},{"name":"Threads","description":"Conversation threads scoped to a hire."},{"name":"Chat","description":"Send a message and receive a JSON or SSE-streamed reply."},{"name":"Tasks","description":"Background tasks queued against a hire."},{"name":"Usage","description":"Per-hire usage and quota status."},{"name":"Documents","description":"Read-only access to knowledge documents."},{"name":"Meta","description":"Spec discovery."}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"mi_live_<random>","description":"Bearer API key minted from your dashboard."}},"headers":{"RateLimitLimit":{"description":"Per-minute request limit for the API key.","schema":{"type":"integer","minimum":0}},"RateLimitRemaining":{"description":"Requests remaining in the current minute window.","schema":{"type":"integer","minimum":0}},"RateLimitReset":{"description":"Seconds until the current rate-limit window resets.","schema":{"type":"integer","minimum":0}},"RetryAfter":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message."}},"additionalProperties":true},"RateLimitError":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"retryAfter":{"type":"integer","minimum":0,"description":"Seconds until the limiter resets."}}}]},"QuotaInfo":{"type":"object","description":"Quota detail attached to a 402 Payment Required response.","properties":{"kind":{"type":"string","enum":["thread","task","tokens"]},"limit":{"type":"integer","minimum":0},"used":{"type":"integer","minimum":0},"resetAt":{"type":"string","format":"date-time"},"tier":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"QuotaError":{"type":"object","required":["error","quota"],"properties":{"error":{"type":"string"},"quota":{"$ref":"#/components/schemas/QuotaInfo"}}},"EmployeeSummary":{"type":"object","required":["slug","name","roleTitle","department","tier"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"roleTitle":{"type":"string"},"department":{"type":"string"},"tier":{"type":"string","enum":["starter","professional","executive"]}}},"Hire":{"type":"object","required":["id","aiEmployeeId","status","startedAt","useCompanyKnowledge","employee"],"properties":{"id":{"type":"integer","format":"int64"},"aiEmployeeId":{"type":"integer","format":"int64"},"status":{"type":"string"},"startedAt":{"type":"string","format":"date-time"},"useCompanyKnowledge":{"type":"boolean"},"employee":{"$ref":"#/components/schemas/EmployeeSummary"}}},"Thread":{"type":"object","required":["id","hireId","userId","aiEmployeeId","title","createdAt","updatedAt"],"properties":{"id":{"type":"integer","format":"int64"},"hireId":{"type":"integer","format":"int64"},"userId":{"type":"integer","format":"int64"},"aiEmployeeId":{"type":"integer","format":"int64"},"title":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":true},"ToolInvocation":{"type":"object","description":"Record of a tool call performed during message generation.","properties":{"name":{"type":"string"},"arguments":{"type":"object","additionalProperties":true},"result":{},"error":{"type":["string","null"]}},"additionalProperties":true},"Citation":{"type":"object","description":"Document citation surfaced by retrieval-augmented generation.","properties":{"documentId":{"type":"integer","format":"int64"},"filename":{"type":"string"},"score":{"type":"number"},"scope":{"type":"string","enum":["hire","company"]}},"additionalProperties":true},"Message":{"type":"object","required":["id","threadId","role","content","createdAt"],"properties":{"id":{"type":"integer","format":"int64"},"threadId":{"type":"integer","format":"int64"},"role":{"type":"string","enum":["user","assistant","system"]},"content":{"type":"string"},"model":{"type":["string","null"]},"promptTokens":{"type":"integer","minimum":0},"completionTokens":{"type":"integer","minimum":0},"totalTokens":{"type":"integer","minimum":0},"costCents":{"type":"integer","minimum":0},"errorMessage":{"type":["string","null"]},"toolInvocations":{"oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/ToolInvocation"}},{"type":"null"}]},"citations":{"oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/Citation"}},{"type":"null"}]},"attachments":{"type":"array","description":"Attachments linked to this message (downloadable artifacts produced or received in this turn).","items":{"$ref":"#/components/schemas/Attachment"}},"createdAt":{"type":"string","format":"date-time"}}},"Usage":{"type":"object","description":"Cumulative usage counters returned by the chat engine.","required":["promptTokens","completionTokens","totalTokens"],"properties":{"promptTokens":{"type":"integer","minimum":0},"completionTokens":{"type":"integer","minimum":0},"totalTokens":{"type":"integer","minimum":0}},"additionalProperties":true},"TaskInput":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","maxLength":20000},"instructions":{"type":"string","maxLength":8000}}},"TaskOutput":{"type":"object","properties":{"text":{"type":"string"}}},"Task":{"type":"object","required":["id","hireId","userId","aiEmployeeId","status","input","queuedAt"],"properties":{"id":{"type":"integer","format":"int64"},"hireId":{"type":"integer","format":"int64"},"userId":{"type":"integer","format":"int64"},"aiEmployeeId":{"type":"integer","format":"int64"},"title":{"type":"string"},"status":{"type":"string","enum":["queued","running","completed","failed"]},"input":{"$ref":"#/components/schemas/TaskInput"},"output":{"oneOf":[{"$ref":"#/components/schemas/TaskOutput"},{"type":"null"}]},"errorMessage":{"type":["string","null"]},"model":{"type":["string","null"]},"promptTokens":{"type":"integer","minimum":0},"completionTokens":{"type":"integer","minimum":0},"totalTokens":{"type":"integer","minimum":0},"costCents":{"type":"integer","minimum":0},"queuedAt":{"type":"string","format":"date-time"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}},"additionalProperties":true},"Document":{"type":"object","required":["id","userId","scope","filename","mimeType","status","createdAt","updatedAt"],"properties":{"id":{"type":"integer","format":"int64"},"hireId":{"type":["integer","null"],"format":"int64"},"userId":{"type":"integer","format":"int64"},"aiEmployeeId":{"type":["integer","null"],"format":"int64"},"scope":{"type":"string","enum":["hire","company"]},"filename":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"integer","minimum":0},"status":{"type":"string","enum":["pending","processing","ready","failed"]},"errorMessage":{"type":["string","null"]},"chunkCount":{"type":"integer","minimum":0},"enabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":true},"TierLimits":{"type":"object","required":["maxThreadsPerMonth","maxTasksPerMonth","maxTokensPerMonth","maxDocuments","maxDocumentBytes"],"properties":{"maxThreadsPerMonth":{"type":"integer","minimum":0},"maxTasksPerMonth":{"type":"integer","minimum":0},"maxTokensPerMonth":{"type":"integer","minimum":0},"maxDocuments":{"type":"integer","minimum":0},"maxDocumentBytes":{"type":"integer","minimum":0}}},"QuotaUsed":{"type":"object","required":["threads","tasks","promptTokens","completionTokens","totalTokens"],"properties":{"threads":{"type":"integer","minimum":0},"tasks":{"type":"integer","minimum":0},"promptTokens":{"type":"integer","minimum":0},"completionTokens":{"type":"integer","minimum":0},"totalTokens":{"type":"integer","minimum":0}}},"QuotaRemaining":{"type":"object","required":["threads","tasks","tokens"],"properties":{"threads":{"type":"integer","minimum":0},"tasks":{"type":"integer","minimum":0},"tokens":{"type":"integer","minimum":0}}},"QuotaStatus":{"type":"object","required":["tier","limits","used","remaining","resetAt","periodStart"],"properties":{"tier":{"type":"string"},"limits":{"$ref":"#/components/schemas/TierLimits"},"used":{"$ref":"#/components/schemas/QuotaUsed"},"remaining":{"$ref":"#/components/schemas/QuotaRemaining"},"resetAt":{"type":"string","format":"date-time"},"periodStart":{"type":"string","format":"date-time"}}},"UsageTotals":{"type":"object","required":["messages","tasks","promptTokens","completionTokens","totalTokens","costCents"],"properties":{"messages":{"type":"integer","minimum":0},"tasks":{"type":"integer","minimum":0},"promptTokens":{"type":"integer","minimum":0},"completionTokens":{"type":"integer","minimum":0},"totalTokens":{"type":"integer","minimum":0},"costCents":{"type":"integer","minimum":0}}},"ListHiresResponse":{"type":"object","required":["hires"],"properties":{"hires":{"type":"array","items":{"$ref":"#/components/schemas/Hire"}}}},"GetHireResponse":{"type":"object","required":["hire"],"properties":{"hire":{"$ref":"#/components/schemas/Hire"}}},"ListThreadsResponse":{"type":"object","required":["threads"],"properties":{"threads":{"type":"array","items":{"$ref":"#/components/schemas/Thread"}}}},"CreateThreadRequest":{"type":"object","properties":{"title":{"type":"string","maxLength":200}}},"CreateThreadResponse":{"type":"object","required":["thread"],"properties":{"thread":{"$ref":"#/components/schemas/Thread"}}},"GetThreadResponse":{"type":"object","required":["thread","messages"],"properties":{"thread":{"$ref":"#/components/schemas/Thread"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}}}},"SendMessageRequest":{"type":"object","description":"Either `content` or `attachmentIds` (or both) must be provided.","properties":{"content":{"type":"string","maxLength":20000},"attachmentIds":{"type":"array","description":"IDs of attachments uploaded via POST /hires/{hireId}/attachments to include with this message. Maximum 10 per message.","items":{"type":"integer","minimum":1},"maxItems":10},"attachments":{"type":"array","description":"Alias for `attachmentIds`. Accepted for parity with the documented contract; ignored when `attachmentIds` is also present.","items":{"type":"integer","minimum":1},"maxItems":10}},"anyOf":[{"required":["content"]},{"required":["attachmentIds"]},{"required":["attachments"]}]},"Attachment":{"type":"object","required":["id","hireId","kind","originalName","mimeType","sizeBytes","createdAt","downloadUrl"],"properties":{"id":{"type":"integer"},"hireId":{"type":"integer"},"threadId":{"type":["integer","null"]},"messageId":{"type":["integer","null"]},"kind":{"type":"string","enum":["image","document","audio"]},"originalName":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"integer","minimum":0},"hasExtractedText":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"downloadUrl":{"type":"string"}}},"ListAttachmentsResponse":{"type":"object","required":["attachments"],"properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}}}},"UploadAttachmentResponse":{"type":"object","required":["attachment"],"properties":{"attachment":{"$ref":"#/components/schemas/Attachment"}}},"SendMessageResponse":{"type":"object","required":["userMessage","assistantMessage","usage"],"properties":{"userMessage":{"$ref":"#/components/schemas/Message"},"assistantMessage":{"$ref":"#/components/schemas/Message"},"usage":{"$ref":"#/components/schemas/Usage"},"costCents":{"type":"integer","minimum":0},"model":{"type":["string","null"]}}},"CreateTaskRequest":{"type":"object","required":["prompt"],"properties":{"title":{"type":"string","maxLength":200},"prompt":{"type":"string","minLength":1,"maxLength":20000},"instructions":{"type":"string","maxLength":8000}}},"CreateTaskResponse":{"type":"object","required":["task"],"properties":{"task":{"$ref":"#/components/schemas/Task"}}},"ListTasksResponse":{"type":"object","required":["tasks"],"properties":{"tasks":{"type":"array","items":{"$ref":"#/components/schemas/Task"}}}},"GetTaskResponse":{"type":"object","required":["task"],"properties":{"task":{"$ref":"#/components/schemas/Task"}}},"UsageResponse":{"type":"object","required":["usage","quota"],"properties":{"usage":{"$ref":"#/components/schemas/UsageTotals"},"quota":{"$ref":"#/components/schemas/QuotaStatus"}}},"ListDocumentsResponse":{"type":"object","required":["documents"],"properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/Document"}}}}},"responses":{"BadRequest":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing, invalid, revoked, or wrong-kind API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found or not visible to this API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"QuotaExceeded":{"description":"Plan quota exceeded for this hire.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuotaError"}}}},"RateLimited":{"description":"Per-key rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"UpstreamError":{"description":"Upstream AI provider returned an error or timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServiceUnavailable":{"description":"AI runtime is not configured on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":{"HireId":{"name":"hireId","in":"path","required":true,"description":"Numeric identifier of the hire.","schema":{"type":"integer","format":"int64","minimum":1}},"ThreadId":{"name":"threadId","in":"path","required":true,"description":"Numeric identifier of the thread.","schema":{"type":"integer","format":"int64","minimum":1}},"TaskId":{"name":"taskId","in":"path","required":true,"description":"Numeric identifier of the task.","schema":{"type":"integer","format":"int64","minimum":1}},"StreamQuery":{"name":"stream","in":"query","required":false,"description":"Set to `true` to receive a Server-Sent Events stream instead of a single JSON object.","schema":{"type":"string","enum":["true","false","1","0","yes"]}},"UsageSinceQuery":{"name":"since","in":"query","required":false,"description":"ISO-8601 timestamp; usage totals are aggregated from this instant forward.","schema":{"type":"string","format":"date-time"}}}},"paths":{"/hires":{"get":{"operationId":"listHires","summary":"List active hires","tags":["Hires"],"responses":{"200":{"description":"Active hires for the API key owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListHiresResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/hires/{hireId}":{"get":{"operationId":"getHire","summary":"Get a hire","tags":["Hires"],"parameters":[{"$ref":"#/components/parameters/HireId"}],"responses":{"200":{"description":"The hire record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetHireResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/hires/{hireId}/threads":{"post":{"operationId":"createThread","summary":"Create a thread","tags":["Threads"],"parameters":[{"$ref":"#/components/parameters/HireId"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateThreadRequest"}}}},"responses":{"201":{"description":"Thread created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateThreadResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"get":{"operationId":"listThreads","summary":"List threads for a hire","tags":["Threads"],"parameters":[{"$ref":"#/components/parameters/HireId"}],"responses":{"200":{"description":"Threads for the hire.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListThreadsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/hires/{hireId}/threads/{threadId}":{"get":{"operationId":"getThread","summary":"Get a thread (with messages)","tags":["Threads"],"parameters":[{"$ref":"#/components/parameters/HireId"},{"$ref":"#/components/parameters/ThreadId"}],"responses":{"200":{"description":"Thread with its message history.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetThreadResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/hires/{hireId}/threads/{threadId}/messages":{"post":{"operationId":"sendMessage","summary":"Send a chat message and get a JSON reply (or SSE stream)","description":"Default response is a single JSON object. Pass `?stream=true` or `Accept: text/event-stream` to receive an SSE stream of `user_message`, `assistant_delta`, `done`, and `error` events.","tags":["Chat"],"parameters":[{"$ref":"#/components/parameters/HireId"},{"$ref":"#/components/parameters/ThreadId"},{"$ref":"#/components/parameters/StreamQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"}}}},"responses":{"200":{"description":"Either a JSON reply or an SSE stream (depending on negotiation).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResponse"}},"text/event-stream":{"schema":{"type":"string","description":"Server-Sent Events stream emitting `user_message`, `assistant_delta`, `done`, and `error` events."}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"502":{"$ref":"#/components/responses/UpstreamError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/hires/{hireId}/attachments":{"get":{"operationId":"listAttachments","summary":"List attachments uploaded for a hire","tags":["Attachments"],"parameters":[{"$ref":"#/components/parameters/HireId"},{"name":"threadId","in":"query","required":false,"description":"Filter to attachments tied to a specific thread.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Attachments visible to the API key owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListAttachmentsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"operationId":"uploadAttachment","summary":"Upload an attachment (image, document, or audio) for a hire","description":"Send `multipart/form-data` with a `file` field (required) and an optional `threadId` field. Max 25MB per file.","tags":["Attachments"],"parameters":[{"$ref":"#/components/parameters/HireId"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"threadId":{"type":"integer","minimum":1}}}}}},"responses":{"201":{"description":"Attachment created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadAttachmentResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/hires/{hireId}/attachments/{attachmentId}":{"delete":{"operationId":"deleteAttachment","summary":"Delete an attachment","tags":["Attachments"],"parameters":[{"$ref":"#/components/parameters/HireId"},{"name":"attachmentId","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/attachments/{attachmentId}":{"delete":{"operationId":"deleteAttachmentAlias","summary":"Delete an attachment by id (alias of /hires/{hireId}/attachments/{attachmentId})","description":"Spec-aligned alias that resolves the owning hire from the attachment record after authenticating ownership. Behaves identically to the canonical hire-scoped delete route.","tags":["Attachments"],"parameters":[{"name":"attachmentId","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/hires/{hireId}/attachments/{attachmentId}/download":{"get":{"operationId":"downloadAttachment","summary":"Download the original attachment binary","tags":["Attachments"],"parameters":[{"$ref":"#/components/parameters/HireId"},{"name":"attachmentId","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Binary attachment payload.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/hires/{hireId}/tasks":{"post":{"operationId":"createTask","summary":"Queue a background task","tags":["Tasks"],"parameters":[{"$ref":"#/components/parameters/HireId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTaskRequest"}}}},"responses":{"201":{"description":"Task queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTaskResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"get":{"operationId":"listTasks","summary":"List tasks for a hire","tags":["Tasks"],"parameters":[{"$ref":"#/components/parameters/HireId"}],"responses":{"200":{"description":"Tasks for the hire.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListTasksResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/hires/{hireId}/tasks/{taskId}":{"get":{"operationId":"getTask","summary":"Get a task","tags":["Tasks"],"parameters":[{"$ref":"#/components/parameters/HireId"},{"$ref":"#/components/parameters/TaskId"}],"responses":{"200":{"description":"The task record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTaskResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/hires/{hireId}/usage":{"get":{"operationId":"getUsage","summary":"Get usage and quota status for a hire","tags":["Usage"],"parameters":[{"$ref":"#/components/parameters/HireId"},{"$ref":"#/components/parameters/UsageSinceQuery"}],"responses":{"200":{"description":"Usage totals and quota status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/hires/{hireId}/documents":{"get":{"operationId":"listHireDocuments","summary":"List hire-scoped knowledge documents","tags":["Documents"],"parameters":[{"$ref":"#/components/parameters/HireId"}],"responses":{"200":{"description":"Documents attached to the hire.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListDocumentsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/documents":{"get":{"operationId":"listCompanyDocuments","summary":"List company-scoped knowledge documents","tags":["Documents"],"responses":{"200":{"description":"Company-scoped documents for the API key owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListDocumentsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/sites":{"get":{"operationId":"listSites","summary":"List tracked sites (audit schedules) for the API key owner.","tags":["Sites"],"responses":{"200":{"description":"Array of sites.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/audits":{"post":{"operationId":"triggerAudit","summary":"Trigger an on-demand audit for a URL.","tags":["Audits"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"responses":{"202":{"description":"Audit queued. Returns slug + status=pending.","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"status":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/audits/latest":{"get":{"operationId":"getLatestAudit","summary":"Latest audit for a given URL (with full reportData and recommendations).","tags":["Audits"],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"}}],"responses":{"200":{"description":"Latest audit + reportData.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/audits/{slug}":{"get":{"operationId":"getAuditBySlug","summary":"Fetch a specific audit, its reportData, and the resolved-recommendation list.","tags":["Audits"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Audit detail.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/recommendations/{auditSlug}/{key}/resolve":{"post":{"operationId":"resolveRecommendation","summary":"Mark an audit recommendation as resolved.","tags":["Recommendations"],"parameters":[{"name":"auditSlug","in":"path","required":true,"schema":{"type":"string"}},{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/recommendations/{auditSlug}/{key}/push-fix":{"post":{"operationId":"pushRecommendationFix","summary":"Push a recommended fix to a connected WordPress site (queued).","tags":["Recommendations"],"parameters":[{"name":"auditSlug","in":"path","required":true,"schema":{"type":"string"}},{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Queued.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"412":{"description":"No verified WordPress connection.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"remediation":{"type":"string"}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/competitors":{"get":{"operationId":"listCompetitors","summary":"List tracked competitors, optionally filtered by site.","tags":["Competitors"],"parameters":[{"name":"siteUrl","in":"query","required":false,"schema":{"type":"string","format":"uri"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"operationId":"addCompetitor","summary":"Add a competitor for a site.","tags":["Competitors"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["siteUrl","competitorUrl"],"properties":{"siteUrl":{"type":"string","format":"uri"},"competitorUrl":{"type":"string","format":"uri"},"label":{"type":"string"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/openapi.json":{"get":{"operationId":"getOpenApiSpec","summary":"Fetch this OpenAPI document","tags":["Meta"],"security":[],"responses":{"200":{"description":"The OpenAPI document for this API.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}