{"openapi":"3.1.0","info":{"title":"Phantom Agent API","version":"1.0.0","description":"Create and retrieve asynchronous Phantom Agent text investigations and inspect the current Credits balance."},"servers":[{"url":"https://phantomhelix.com"}],"security":[{"PhantomAgentApiKey":[]}],"paths":{"/api/v1/phantom-agent/investigations":{"post":{"operationId":"createInvestigation","summary":"Create a text investigation","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvestigationRequest"}}}},"responses":{"202":{"description":"Investigation accepted","headers":{"Location":{"schema":{"type":"string"}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvestigationResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"403":{"$ref":"#/components/responses/AccessRequired"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"description":"Request rate limit exceeded","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}}},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/DependencyUnavailable"}}}},"/api/v1/phantom-agent/investigations/{id}":{"get":{"operationId":"getInvestigationStatus","summary":"Get investigation status","parameters":[{"$ref":"#/components/parameters/InvestigationId"}],"responses":{"200":{"description":"Current factual investigation state","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvestigationStatus"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"403":{"$ref":"#/components/responses/AccessRequired"},"404":{"$ref":"#/components/responses/InvestigationNotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/DependencyUnavailable"}}}},"/api/v1/phantom-agent/investigations/{id}/report":{"get":{"operationId":"getInvestigationReport","summary":"Get a completed investigation report","parameters":[{"$ref":"#/components/parameters/InvestigationId"}],"responses":{"200":{"description":"Complete structured and Markdown report","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvestigationReportResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"403":{"$ref":"#/components/responses/AccessRequired"},"404":{"$ref":"#/components/responses/InvestigationNotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"409":{"description":"Report is not ready or unavailable","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/DependencyUnavailable"}}}},"/api/v1/phantom-agent/credits":{"get":{"operationId":"getCreditBalance","summary":"Get the current Credits balance","responses":{"200":{"description":"Current available and reserved Credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditBalance"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"403":{"$ref":"#/components/responses/AccessRequired"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/DependencyUnavailable"}}}}},"components":{"securitySchemes":{"PhantomAgentApiKey":{"type":"http","scheme":"bearer"}},"parameters":{"InvestigationId":{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^inv_[a-f0-9]{64}$"}}},"headers":{"RequestId":{"description":"Identifier for support correlation","schema":{"type":"string"}},"RetryAfter":{"description":"Seconds to wait before retrying","schema":{"type":"integer","minimum":1}}},"responses":{"InvalidRequest":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}}},"InvalidApiKey":{"description":"Missing, malformed, unknown, or revoked API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}}},"AccessRequired":{"description":"Current account access is required","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}}},"InvestigationNotFound":{"description":"Investigation is absent or not owned by this account","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}}},"MethodNotAllowed":{"description":"Request method is not allowed","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}}},"Conflict":{"description":"Insufficient Credits, idempotency conflict, or an identical request still being accepted","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}}},"PayloadTooLarge":{"description":"Request body is too large","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}}},"RateLimited":{"description":"Request rate limit exceeded","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}}},"InternalError":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}}},"DependencyUnavailable":{"description":"Required dependency is temporarily unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}}}},"schemas":{"CreateInvestigationRequest":{"type":"object","additionalProperties":false,"required":["query","max_credits"],"properties":{"query":{"type":"string","minLength":1,"maxLength":4000},"max_credits":{"type":"integer","minimum":5},"client_reference":{"type":"string","minLength":1,"maxLength":200}}},"InvestigationState":{"type":"string","enum":["queued","starting","running","completed","failed","cancelled"]},"CreateInvestigationResponse":{"type":"object","additionalProperties":false,"required":["id","status","client_reference","status_url","report_url","created_at"],"properties":{"id":{"type":"string","pattern":"^inv_[a-f0-9]{64}$"},"status":{"$ref":"#/components/schemas/InvestigationState"},"client_reference":{"type":["string","null"]},"status_url":{"type":"string"},"report_url":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"InvestigationStatus":{"type":"object","additionalProperties":false,"required":["id","status","client_reference","created_at","started_at","completed_at","failed_at","cancelled_at","report_url"],"properties":{"id":{"type":"string","pattern":"^inv_[a-f0-9]{64}$"},"status":{"type":"string","enum":["queued","starting","running","completed","failed","cancelled"]},"client_reference":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"failed_at":{"type":["string","null"],"format":"date-time"},"cancelled_at":{"type":["string","null"],"format":"date-time"},"report_url":{"type":"string"}}},"ReportSectionItem":{"type":"object","additionalProperties":false,"required":["heading","body","metadata","citation_ids"],"properties":{"heading":{"type":["string","null"]},"body":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":["string","number","boolean","null"]}},"citation_ids":{"type":"array","items":{"type":"string"}}}},"ReportSection":{"type":"object","additionalProperties":false,"required":["id","title","items"],"properties":{"id":{"type":"string","enum":["scope","executive_summary","findings","timeline","sources","next_actions"]},"title":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ReportSectionItem"}}}},"Citation":{"type":"object","additionalProperties":false,"required":["id","title","url"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":["string","null"],"format":"uri"}}},"PublicReport":{"type":"object","additionalProperties":false,"required":["title","summary","sections","markdown","citations","gaps","warnings","pdf_download_url"],"properties":{"title":{"type":"string"},"summary":{"type":["string","null"]},"sections":{"type":"array","minItems":6,"maxItems":6,"items":{"$ref":"#/components/schemas/ReportSection"}},"markdown":{"type":"string"},"citations":{"type":"array","items":{"$ref":"#/components/schemas/Citation"}},"gaps":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"pdf_download_url":{"type":["string","null"],"format":"uri"}}},"InvestigationReportResponse":{"type":"object","additionalProperties":false,"required":["investigation_id","status","client_reference","completed_at","report"],"properties":{"investigation_id":{"type":"string","pattern":"^inv_[a-f0-9]{64}$"},"status":{"const":"completed"},"client_reference":{"type":["string","null"]},"completed_at":{"type":"string","format":"date-time"},"report":{"$ref":"#/components/schemas/PublicReport"}}},"CreditBalance":{"type":"object","additionalProperties":false,"required":["available","reserved","currency","as_of"],"properties":{"available":{"type":"integer","minimum":0},"reserved":{"type":"integer","minimum":0},"currency":{"const":"credits"},"as_of":{"type":"string","format":"date-time"}}},"PublicError":{"type":"object","additionalProperties":false,"required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["INVALID_REQUEST","PAYLOAD_TOO_LARGE","INVALID_API_KEY","ACCESS_REQUIRED","INVESTIGATION_NOT_FOUND","INSUFFICIENT_CREDITS","IDEMPOTENCY_CONFLICT","IDEMPOTENCY_KEY_RETIRED","REQUEST_IN_PROGRESS","REQUEST_REJECTED","CONCURRENCY_LIMIT_REACHED","REPORT_NOT_READY","REPORT_UNAVAILABLE","RATE_LIMITED","DEPENDENCY_UNAVAILABLE","INTERNAL_ERROR"]},"message":{"type":"string"},"request_id":{"type":"string"},"status":{"$ref":"#/components/schemas/InvestigationState"}}},"PublicErrorEnvelope":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"$ref":"#/components/schemas/PublicError"}}}}}}