{"openapi":"3.1.0","info":{"title":"Skaitra API","version":"1","description":"Skaitra's resource API, for automation, AI agents and the app itself. Authenticate with `Authorization: Bearer skt_…` (an API key acts as its service principal, with that principal's scopes and companies) or with an OAuth access token for the Skaitra resource (`/mcp`), which acts as its user or service principal. Changes an agent must not make on its own (e.g. widening what AI agents may do) answer 403 `APPROVAL_REQUIRED` with an approval link; repeat the request with `Approval-Id` once an admin approved it. Requests are limited per key or token."},"servers":[{"url":"https://{agentura}.skaitra.com/api/v1","description":"Jūsų agentūros adresas Skaitroje","variables":{"agentura":{"default":"jusu-agentura","description":"Jūsų agentūros adresas Skaitroje; agentūros savas domenas taip pat tinka"}}}],"security":[{"apiKey":[]},{"oauth":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Skaitra API key (`skt_…`)."},"oauth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.1 access token issued for the Skaitra resource (`/mcp`); see /.well-known/oauth-protected-resource."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["INVALID_API_KEY","INSUFFICIENT_SCOPE","COMPANY_ACCESS_DENIED","NOT_FOUND","VALIDATION_ERROR","INVALID_CURSOR","METHOD_NOT_ALLOWED","PRECONDITION_REQUIRED","PRECONDITION_FAILED","IDEMPOTENCY_KEY_REUSED","IDEMPOTENCY_KEY_IN_USE","CONFLICT","PAYLOAD_TOO_LARGE","UNSUPPORTED_MEDIA_TYPE","STORAGE_UNAVAILABLE","FORBIDDEN","FEATURE_NOT_INCLUDED","RATE_LIMITED","APPROVAL_REQUIRED","APPROVAL_PENDING","APPROVAL_REJECTED","INTERNAL_ERROR"]},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"shortName":{"type":["string","null"]},"registrationCode":{"type":["string","null"]},"vatCode":{"type":["string","null"]},"legalForm":{"type":["string","null"]},"address":{"type":["string","null"]},"directorName":{"type":["string","null"]},"vatPeriod":{"anyOf":[{"type":"string","enum":["monthly","quarterly","semiannual"]},{"type":"null"}]},"vatFrom":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"vatTo":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"employeesFrom":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"employeesTo":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"serviceStoppedFrom":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"serviceStoppedReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","shortName","registrationCode","vatCode","legalForm","address","directorName","vatPeriod","vatFrom","vatTo","employeesFrom","employeesTo","serviceStoppedFrom","serviceStoppedReason","createdAt","updatedAt"],"additionalProperties":false},"CompanyUpdate":{"type":"object","properties":{"shortName":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"legalForm":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"address":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"directorName":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"vatPeriod":{"anyOf":[{"type":"string","enum":["monthly","quarterly","semiannual"]},{"type":"null"}]},"vatFrom":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"vatTo":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"employeesFrom":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"employeesTo":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"serviceStoppedFrom":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"serviceStoppedReason":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}},"additionalProperties":false},"CompanySettings":{"type":"object","properties":{"companyId":{"type":"string"},"export":{"anyOf":[{"$ref":"#/components/schemas/ExportSettings"},{"type":"null"}]},"accountingPolicy":{"type":"object","properties":{"configured":{"type":"boolean"},"fields":{"minItems":5,"maxItems":5,"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["warehouse","type","journal","allocation","vatClass"]},"required":{"type":"boolean"},"automatic":{"type":"boolean"},"defaultValue":{"anyOf":[{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"type"},"catalogEntryId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"code":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","catalogEntryId","code","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"journal"},"catalogEntryId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"code":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","catalogEntryId","code","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"account"},"catalogEntryId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"code":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","catalogEntryId","code","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"item"},"catalogEntryId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"code":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","catalogEntryId","code","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"service"},"catalogEntryId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"code":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","catalogEntryId","code","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"warehouse"},"catalogEntryId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"code":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","catalogEntryId","code","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"vat_class"},"catalogEntryId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"code":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","catalogEntryId","code","label"],"additionalProperties":false}]},{"type":"null"}]}},"required":["field","required","automatic","defaultValue"],"additionalProperties":false}}},"required":["configured","fields"],"additionalProperties":false},"agent":{"type":"object","properties":{"configured":{"type":"boolean"},"mcpEnabled":{"type":"boolean"},"documentReview":{"type":"boolean"},"accountingData":{"type":"boolean"},"finvaldaRead":{"type":"boolean"},"finvaldaWritePolicy":{"type":"string","enum":["disabled","requires_approval"]},"tier2ClarificationEnabled":{"type":"boolean"}},"required":["configured","mcpEnabled","documentReview","accountingData","finvaldaRead","finvaldaWritePolicy","tier2ClarificationEnabled"],"additionalProperties":false}},"required":["companyId","export","accountingPolicy","agent"],"additionalProperties":false},"ExportSettings":{"type":"object","properties":{"baseCurrency":{"type":"string","pattern":"^[A-Z]{3}$"},"companyCountryCode":{"type":"string","pattern":"^[A-Z]{2}$"},"xmlImportParameter":{"type":"string","minLength":1}},"required":["baseCurrency","companyCountryCode","xmlImportParameter"],"additionalProperties":false},"CompanySettingsUpdate":{"type":"object","properties":{"export":{"$ref":"#/components/schemas/ExportSettings"},"accountingPolicy":{"type":"object","properties":{"fields":{"minItems":5,"maxItems":5,"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["warehouse","type","journal","allocation","vatClass"]},"required":{"type":"boolean"},"automatic":{"type":"boolean"},"defaultValue":{"anyOf":[{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"type"},"catalogEntryId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"code":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","catalogEntryId","code","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"journal"},"catalogEntryId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"code":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","catalogEntryId","code","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"account"},"catalogEntryId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"code":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","catalogEntryId","code","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"item"},"catalogEntryId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"code":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","catalogEntryId","code","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"service"},"catalogEntryId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"code":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","catalogEntryId","code","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"warehouse"},"catalogEntryId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"code":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","catalogEntryId","code","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"vat_class"},"catalogEntryId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"code":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","catalogEntryId","code","label"],"additionalProperties":false}]},{"type":"null"}]}},"required":["field","required","automatic","defaultValue"],"additionalProperties":false}}},"required":["fields"],"additionalProperties":false},"agent":{"type":"object","properties":{"mcpEnabled":{"type":"boolean"},"documentReview":{"type":"boolean"},"accountingData":{"type":"boolean"},"finvaldaRead":{"type":"boolean"},"finvaldaWritePolicy":{"type":"string","enum":["disabled","requires_approval"]},"tier2ClarificationEnabled":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false},"CompanyPlaybook":{"type":"object","properties":{"companyId":{"type":"string"},"markdown":{"type":"string"},"rules":{"type":"object","properties":{"visualReview":{"type":"object","properties":{"enabled":{"type":"boolean"},"target":{"type":"string","const":"detailed_line.description"},"instruction":{"type":"string","minLength":1,"maxLength":500}},"required":["enabled","target","instruction"],"additionalProperties":false}},"required":["visualReview"],"additionalProperties":false},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"updatedAt":{"type":"string"}},"required":["companyId","markdown","rules","version","updatedAt"],"additionalProperties":false},"Document":{"type":"object","properties":{"id":{"type":"string"},"accountingDocumentId":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"companyId":{"type":["string","null"]},"name":{"type":"string"},"originalFilename":{"type":"string"},"source":{"type":"string"},"receivedAt":{"type":"string"},"stage":{"type":"string","enum":["inbox","accounting","storage","archived","split","error"]},"destination":{"anyOf":[{"type":"string","enum":["accounting","storage","none"]},{"type":"null"}]},"duplicateOfDocumentId":{"type":["string","null"]},"file":{"anyOf":[{"type":"object","properties":{"sizeBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"mimeType":{"type":"string"},"sha256":{"type":"string"}},"required":["sizeBytes","mimeType","sha256"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","accountingDocumentId","companyId","name","originalFilename","source","receivedAt","stage","destination","duplicateOfDocumentId","file","createdAt","updatedAt"],"additionalProperties":false},"File":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sha256":{"type":"string"},"createdAt":{"type":"string"},"expiresAt":{"type":"string"},"documentId":{"type":["string","null"]}},"required":["id","filename","mimeType","sizeBytes","sha256","createdAt","expiresAt","documentId"],"additionalProperties":false},"CompanyPeriod":{"type":"object","properties":{"id":{"type":"string"},"companyId":{"type":"string"},"companyName":{"type":"string"},"period":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"primaryAccountantUserId":{"type":["string","null"]},"vatPayer":{"type":"boolean"},"hasEmployees":{"type":"boolean"},"status":{"type":"string","enum":["done","open","overdue"]},"counts":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"done":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"open":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"overdue":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"notApplicable":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["total","done","open","overdue","notApplicable"],"additionalProperties":false},"nextDueDate":{"type":["string","null"]},"obligations":{"type":"array","items":{"$ref":"#/components/schemas/Obligation"}},"documents":{"type":"object","properties":{"received":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"inbox":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"accounting":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["received","inbox","accounting"],"additionalProperties":false},"messages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","companyId","companyName","period","primaryAccountantUserId","vatPayer","hasEmployees","status","counts","nextDueDate","obligations","documents","messages"],"additionalProperties":false},"Obligation":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"companyId":{"type":"string"},"period":{"type":"string"},"code":{"type":"string"},"label":{"type":"string"},"dueDate":{"type":"string"},"status":{"type":"string","enum":["todo","in_progress","waiting","done","not_applicable"]},"statusLabel":{"type":"string"},"assigneeUserId":{"type":["string","null"]},"completionSource":{"anyOf":[{"type":"string","enum":["manual","auto"]},{"type":"null"}]},"completedAt":{"type":["string","null"]},"overdue":{"type":"boolean"}},"required":["id","companyId","period","code","label","dueDate","status","statusLabel","assigneeUserId","completionSource","completedAt","overdue"],"additionalProperties":false},"Task":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"attempt":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"companyId":{"type":"string"},"companyName":{"type":["string","null"]},"subject":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"instruction":{"type":"string"},"humanFeedback":{"type":["string","null"]},"resultStatus":{"type":["string","null"]},"result":{"anyOf":[{},{"type":"null"}]},"createdBy":{"type":"object","properties":{"actorType":{"type":"string"},"userId":{"type":["string","null"]}},"required":["actorType","userId"],"additionalProperties":false},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"completedAt":{"type":["string","null"]}},"required":["id","type","status","attempt","companyId","companyName","subject","instruction","humanFeedback","resultStatus","result","createdBy","createdAt","updatedAt","completedAt"],"additionalProperties":false},"TaskEvent":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"type":{"type":"string"},"actorType":{"type":"string"},"actorId":{"type":["string","null"]},"data":{"anyOf":[{},{"type":"null"}]},"createdAt":{"type":"string"}},"required":["id","type","actorType","actorId","data","createdAt"],"additionalProperties":false},"Event":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["document.received","document.ocr_completed","document.ocr_failed","obligation.updated","task.completed","company.updated","company.settings_updated","webhook.test"]},"createdAt":{"type":"string"},"companyId":{"type":["string","null"]},"subject":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","type","createdAt","companyId","subject","data"],"additionalProperties":false},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"eventTypes":{"type":"array","items":{"anyOf":[{"type":"string","enum":["document.received","document.ocr_completed","document.ocr_failed","obligation.updated","task.completed","company.updated","company.settings_updated","webhook.test"]},{"type":"string","const":"*"}]}},"enabled":{"type":"boolean"},"createdAt":{"type":"string"},"lastSuccessAt":{"type":["string","null"]},"lastFailureAt":{"type":["string","null"]}},"required":["id","url","description","eventTypes","enabled","createdAt","lastSuccessAt","lastFailureAt"],"additionalProperties":false},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"eventId":{"type":"string"},"eventType":{"type":"string","enum":["document.received","document.ocr_completed","document.ocr_failed","obligation.updated","task.completed","company.updated","company.settings_updated","webhook.test"]},"status":{"type":"string","enum":["pending","succeeded","failed"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextAttemptAt":{"type":["string","null"]},"lastStatusCode":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"lastError":{"type":["string","null"]},"createdAt":{"type":"string"},"deliveredAt":{"type":["string","null"]}},"required":["id","eventId","eventType","status","attempts","nextAttemptAt","lastStatusCode","lastError","createdAt","deliveredAt"],"additionalProperties":false},"Approval":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","approved","rejected","used","expired"]},"operationId":{"type":"string"},"companyId":{"type":["string","null"]},"reason":{"type":"string"},"changes":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"before":{},"after":{}},"required":["path","before","after"],"additionalProperties":false}},"approvalUrl":{"type":"string"},"createdAt":{"type":"string"},"expiresAt":{"type":"string"},"decidedAt":{"type":["string","null"]}},"required":["id","status","operationId","companyId","reason","changes","approvalUrl","createdAt","expiresAt","decidedAt"],"additionalProperties":false}}},"paths":{"/companies":{"get":{"operationId":"companies.list","tags":["Companies"],"summary":"List companies","description":"Companies this key may access, ordered by name. `query` matches the name, short name, registration code or VAT code.","x-scopes":["companies:read"],"parameters":[{"name":"query","in":"query","required":false,"description":"Text to search for.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` from the previous page.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":500}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{id}":{"get":{"operationId":"companies.get","tags":["Companies"],"summary":"Get a company","description":"One company by id.","x-scopes":["companies:read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"companies.update","tags":["Companies"],"summary":"Update a company","description":"Changes the given attributes; omitted ones stay. VAT and employee dates decide which monthly work applies. Use `dryRun=true` to preview.","x-scopes":["companies:write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":200}},{"name":"dryRun","in":"query","required":false,"description":"`true` validates and returns the changes without saving them.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique value; a retry with the same key returns the first result.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyUpdate"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Company"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"changes":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"before":{},"after":{}},"required":["path","before","after"],"additionalProperties":false}},"result":{"$ref":"#/components/schemas/Company"}},"required":["dryRun","changes","result"],"additionalProperties":false}]}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with the same Idempotency-Key is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"The resource changed since you read it (If-Match).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The Idempotency-Key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"The operation needs If-Match.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{id}/settings":{"get":{"operationId":"companySettings.get","tags":["Company settings"],"summary":"Get company settings","description":"Configuration of one company: Finvalda export parameters, the accounting field policy and what AI agents may do.","x-scopes":["companies:read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySettings"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"companySettings.update","tags":["Company settings"],"summary":"Update company settings","description":"Changes the given sections. `export` and `accountingPolicy` are replaced whole; `agent` switches are merged. Use `dryRun=true` to see the changes first.","x-scopes":["companies:write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":200}},{"name":"dryRun","in":"query","required":false,"description":"`true` validates and returns the changes without saving them.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique value; a retry with the same key returns the first result.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySettingsUpdate"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CompanySettings"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"changes":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"before":{},"after":{}},"required":["path","before","after"],"additionalProperties":false}},"result":{"$ref":"#/components/schemas/CompanySettings"}},"required":["dryRun","changes","result"],"additionalProperties":false}]}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with the same Idempotency-Key is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"The resource changed since you read it (If-Match).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The Idempotency-Key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"The operation needs If-Match.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{id}/playbook":{"get":{"operationId":"companyPlaybook.get","tags":["Company settings"],"summary":"Get the company playbook","description":"The company's working instructions. The `ETag` header carries the version.","x-scopes":["companies:read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyPlaybook"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"companyPlaybook.replace","tags":["Company settings"],"summary":"Replace the company playbook","description":"Saves new instructions. `If-Match` must carry the version you edited (from `version` or the `ETag`); if someone saved in between, the answer is 412 and nothing changes.","x-scopes":["companies:write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":200}},{"name":"If-Match","in":"header","required":false,"description":"The version being replaced, e.g. `3` or `\"3\"`.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique value; a retry with the same key returns the first result.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"markdown":{"type":"string","maxLength":200000},"rules":{"type":"object","properties":{"visualReview":{"type":"object","properties":{"enabled":{"type":"boolean"},"target":{"type":"string","const":"detailed_line.description"},"instruction":{"type":"string","minLength":1,"maxLength":500}},"required":["enabled","target","instruction"],"additionalProperties":false}},"required":["visualReview"],"additionalProperties":false}},"required":["markdown"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyPlaybook"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with the same Idempotency-Key is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"The resource changed since you read it (If-Match).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The Idempotency-Key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"The operation needs If-Match.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents":{"get":{"operationId":"documents.list","tags":["Documents"],"summary":"List documents","description":"Documents of the companies this key may access, newest first. Filter by company, stage and when they were received.","x-scopes":["documents:read"],"parameters":[{"name":"companyId","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":200}},{"name":"stage","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","enum":["inbox","accounting","storage","archived","split","error"]}},{"name":"receivedFrom","in":"query","required":false,"description":"Inclusive lower bound.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}]}},{"name":"receivedTo","in":"query","required":false,"description":"Exclusive upper bound.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}]}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` from the previous page.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":500}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"documents.create","tags":["Documents"],"summary":"Create a document from a file","description":"Files an uploaded file (POST /files) as a document of a company. It arrives in Gautieji like any other document and is read by OCR. A file becomes at most one document.","x-scopes":["documents:write"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique value; a retry with the same key returns the first result.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileId":{"type":"string","minLength":1,"maxLength":200},"companyId":{"type":"string","minLength":1,"maxLength":200},"filename":{"type":"string","minLength":1,"maxLength":255}},"required":["fileId","companyId"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with the same Idempotency-Key is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"The resource changed since you read it (If-Match).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The Idempotency-Key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"The operation needs If-Match.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}":{"get":{"operationId":"documents.get","tags":["Documents"],"summary":"Get a document","description":"One document by id.","x-scopes":["documents:read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/content":{"get":{"operationId":"documents.content","tags":["Documents"],"summary":"Download a document's original","description":"The original file as received.","x-scopes":["documents:read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/octet-stream":{"schema":{"type":"string","contentMediaType":"application/octet-stream"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/files":{"post":{"operationId":"files.create","tags":["Files"],"summary":"Upload a file","description":"Send the raw bytes as the body with their `Content-Type` (PDF, image, XML…) and the name in `filename`. Then turn the file into a document with POST /documents. Up to 48 MB; unused files are deleted after a day.","x-scopes":["documents:write"],"parameters":[{"name":"filename","in":"query","required":true,"description":"The file's name, with its extension.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":255}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique value; a retry with the same key returns the first result.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"*/*":{"schema":{"type":"string","contentMediaType":"application/octet-stream"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with the same Idempotency-Key is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"The resource changed since you read it (If-Match).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The Idempotency-Key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"The operation needs If-Match.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/files/{id}":{"get":{"operationId":"files.get","tags":["Files"],"summary":"Get an uploaded file","description":"A file this key uploaded.","x-scopes":["documents:read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/files/{id}/content":{"get":{"operationId":"files.content","tags":["Files"],"summary":"Download an uploaded file","description":"The bytes of a file this key uploaded.","x-scopes":["documents:read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/octet-stream":{"schema":{"type":"string","contentMediaType":"application/octet-stream"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/company-periods":{"get":{"operationId":"companyPeriods.list","tags":["Work"],"summary":"List companies' month-end work","description":"The Darbai board for a month: one entry per company this key may access. Filter by `status` to find what is late (`overdue`) or unfinished (`open`).","x-scopes":["work:read"],"parameters":[{"name":"period","in":"query","required":true,"description":"The month, `YYYY-MM`.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},{"name":"companyId","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":200}},{"name":"status","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","enum":["done","open","overdue"]}},{"name":"assigneeUserId","in":"query","required":false,"description":"Only companies with an obligation assigned to this person.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` from the previous page.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":500}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CompanyPeriod"}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/company-periods/{id}":{"get":{"operationId":"companyPeriods.get","tags":["Work"],"summary":"Get one company's month","description":"One company's month-end work, by id (`cp_<YYYY-MM>_<companyId>`).","x-scopes":["work:read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","pattern":"^cp_\\d{4}-\\d{2}_.+$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyPeriod"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/obligations/{id}":{"patch":{"operationId":"obligations.update","tags":["Work"],"summary":"Update an obligation","description":"Sets the status (e.g. `done`) or who is responsible. `done` records the time.","x-scopes":["work:write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique value; a retry with the same key returns the first result.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["todo","in_progress","waiting","done","not_applicable"]},"assigneeUserId":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Obligation"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with the same Idempotency-Key is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"The resource changed since you read it (If-Match).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The Idempotency-Key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"The operation needs If-Match.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tasks":{"get":{"operationId":"tasks.list","tags":["Tasks"],"summary":"List tasks","description":"AI agent tasks of the companies this key may access, newest first.","x-scopes":["tasks:read"],"parameters":[{"name":"companyId","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":200}},{"name":"status","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","enum":["pending","in_progress","completed","failed","cancelled"]}},{"name":"type","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":100}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` from the previous page.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":500}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"tasks.create","tags":["Tasks"],"summary":"Create a task","description":"Queues work for the AI agent from a task template (`type`) about one subject of one company, e.g. `{ \"type\": \"…\", \"subject\": { \"type\": \"company\", \"id\": \"…\" } }`.","x-scopes":["tasks:create"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique value; a retry with the same key returns the first result.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","minLength":1,"maxLength":100},"subject":{"type":"object","properties":{"type":{"type":"string","minLength":1,"maxLength":60},"id":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]}},"required":["type","id"],"additionalProperties":false},"companyId":{"type":"string","minLength":1,"maxLength":200},"instruction":{"type":"string","minLength":1,"maxLength":10000}},"required":["type","subject"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with the same Idempotency-Key is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"The resource changed since you read it (If-Match).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The Idempotency-Key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"The operation needs If-Match.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tasks/{id}":{"get":{"operationId":"tasks.get","tags":["Tasks"],"summary":"Get a task","description":"One task, with its result once submitted.","x-scopes":["tasks:read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","pattern":"^task_[A-Za-z0-9_-]{1,199}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tasks/{id}/result":{"post":{"operationId":"tasks.submitResult","tags":["Tasks"],"summary":"Submit a task's result","description":"Finishes the task with the result its template expects (`status` plus the template's fields). A task takes one result.","x-scopes":["tasks:write_result"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","pattern":"^task_[A-Za-z0-9_-]{1,199}$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique value; a retry with the same key returns the first result.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","minLength":1}},"required":["status"],"additionalProperties":{}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with the same Idempotency-Key is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"The resource changed since you read it (If-Match).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The Idempotency-Key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"The operation needs If-Match.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tasks/{id}/events":{"get":{"operationId":"taskEvents.list","tags":["Tasks"],"summary":"List a task's history","description":"What happened to the task, newest first (up to 200 events).","x-scopes":["tasks:read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","pattern":"^task_[A-Za-z0-9_-]{1,199}$"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","default":50,"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaskEvent"}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"taskEvents.create","tags":["Tasks"],"summary":"Comment on a task","description":"Adds a comment to the task's history without starting a new attempt.","x-scopes":["tasks:read","tasks:create"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","pattern":"^task_[A-Za-z0-9_-]{1,199}$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique value; a retry with the same key returns the first result.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","const":"comment"},"body":{"type":"string","minLength":1,"maxLength":5000}},"required":["type","body"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskEvent"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with the same Idempotency-Key is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"The resource changed since you read it (If-Match).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The Idempotency-Key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"The operation needs If-Match.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events":{"get":{"operationId":"events.list","tags":["Events"],"summary":"List events","description":"Events of the companies this key may access, oldest first. Poll with `after` set to the last `nextCursor`: it always points past the newest event returned (or stays put when nothing new happened).","x-scopes":["events:read"],"parameters":[{"name":"after","in":"query","required":false,"description":"`nextCursor` from the previous call.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":100}},{"name":"type","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","enum":["document.received","document.ocr_completed","document.ocr_failed","obligation.updated","task.completed","company.updated","company.settings_updated","webhook.test"]}},{"name":"companyId","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","default":50,"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhook-endpoints":{"get":{"operationId":"webhookEndpoints.list","tags":["Webhooks"],"summary":"List webhook endpoints","description":"The endpoints of this key's service principal.","x-scopes":["webhooks:manage"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"webhookEndpoints.create","tags":["Webhooks"],"summary":"Add a webhook endpoint","description":"Events are POSTed as JSON and signed per the Standard Webhooks spec (`webhook-id`, `webhook-timestamp`, `webhook-signature`). The signing `secret` is returned once. Failed deliveries are retried for about a day.","x-scopes":["webhooks:manage"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique value; a retry with the same key returns the first result.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri","description":"An https:// address."},"eventTypes":{"minItems":1,"maxItems":9,"type":"array","items":{"anyOf":[{"type":"string","enum":["document.received","document.ocr_completed","document.ocr_failed","obligation.updated","task.completed","company.updated","company.settings_updated","webhook.test"]},{"type":"string","const":"*"}]}},"description":{"type":"string","maxLength":300}},"required":["url","eventTypes"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"endpoint":{"$ref":"#/components/schemas/WebhookEndpoint"},"secret":{"type":"string"}},"required":["endpoint","secret"],"additionalProperties":false}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with the same Idempotency-Key is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"The resource changed since you read it (If-Match).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The Idempotency-Key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"The operation needs If-Match.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhook-endpoints/{id}":{"get":{"operationId":"webhookEndpoints.get","tags":["Webhooks"],"summary":"Get a webhook endpoint","description":"One endpoint of this key's service principal.","x-scopes":["webhooks:manage"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","pattern":"^whe_[a-f0-9]{32}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"webhookEndpoints.update","tags":["Webhooks"],"summary":"Update a webhook endpoint","description":"Changes the address, the event types, the description, or pauses it (`enabled: false`).","x-scopes":["webhooks:manage"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","pattern":"^whe_[a-f0-9]{32}$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique value; a retry with the same key returns the first result.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri","description":"An https:// address."},"eventTypes":{"minItems":1,"maxItems":9,"type":"array","items":{"anyOf":[{"type":"string","enum":["document.received","document.ocr_completed","document.ocr_failed","obligation.updated","task.completed","company.updated","company.settings_updated","webhook.test"]},{"type":"string","const":"*"}]}},"description":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"enabled":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with the same Idempotency-Key is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"The resource changed since you read it (If-Match).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The Idempotency-Key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"The operation needs If-Match.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"webhookEndpoints.delete","tags":["Webhooks"],"summary":"Delete a webhook endpoint","description":"Stops deliveries and forgets the endpoint.","x-scopes":["webhooks:manage"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","pattern":"^whe_[a-f0-9]{32}$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique value; a retry with the same key returns the first result.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":["id","deleted"],"additionalProperties":false}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with the same Idempotency-Key is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"The resource changed since you read it (If-Match).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The Idempotency-Key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"The operation needs If-Match.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhook-endpoints/{id}/test":{"post":{"operationId":"webhookEndpoints.test","tags":["Webhooks"],"summary":"Send a test event","description":"Sends a `webhook.test` event now and reports how the endpoint answered.","x-scopes":["webhooks:manage"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","pattern":"^whe_[a-f0-9]{32}$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique value; a retry with the same key returns the first result.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with the same Idempotency-Key is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"The resource changed since you read it (If-Match).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The Idempotency-Key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"The operation needs If-Match.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhook-endpoints/{id}/deliveries":{"get":{"operationId":"webhookDeliveries.list","tags":["Webhooks"],"summary":"List an endpoint's deliveries","description":"Recent deliveries to one endpoint, newest first, to see what failed and why.","x-scopes":["webhooks:manage"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","pattern":"^whe_[a-f0-9]{32}$"}},{"name":"status","in":"query","required":false,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","enum":["pending","succeeded","failed"]}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` from the previous page.","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":500}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/approvals/{id}":{"get":{"operationId":"approvals.get","tags":["Approvals"],"summary":"Get an approval","description":"Where an approval this key asked for stands. Once `approved`, repeat the original request with the header `Approval-Id: <id>`; it can be used once.","x-scopes":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","pattern":"^apr_[a-f0-9]{32}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Approval"}}}},"400":{"description":"The request is invalid; `error.details.issues` lists the problems.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks a scope or access to the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}