{"openapi":"3.1.0","info":{"title":"TaxPio API","version":"2026-09-06","description":"Tax infrastructure for software: deterministic calculations now, documents, records and controlled filing workflows as they open. Every error is `{ error, code, requestId }`; every response carries `x-request-id`.","termsOfService":"https://taxpio.com/legal","contact":{"name":"TaxPio","url":"https://taxpio.com/contact"}},"servers":[{"url":"https://api.taxpio.com"}],"externalDocs":{"url":"https://docs.taxpio.com","description":"Guides and reference."},"tags":[{"name":"Platform"},{"name":"Tax calculations"},{"name":"Sandbox"},{"name":"Connections"},{"name":"Webhooks"},{"name":"Usage and credits"}],"security":[{"bearerKey":[]}],"paths":{"/v1":{"get":{"operationId":"getIndex","tags":["Platform"],"summary":"API index: version, documentation and where to start.","security":[],"responses":{"200":{"description":"The index."}}}},"/v1/health":{"get":{"operationId":"getHealth","tags":["Platform"],"summary":"Liveness: the release and its database answer.","security":[],"responses":{"200":{"description":"Healthy."},"503":{"description":"The database does not answer."}}}},"/v1/me":{"get":{"operationId":"getMe","tags":["Platform"],"summary":"The workspace, application, environment and scopes behind the key.","security":[{"bearerKey":[]}],"responses":{"200":{"description":"The principal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Principal"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tax/programs":{"get":{"operationId":"listTaxPrograms","tags":["Tax calculations"],"summary":"The calculation programs and their inputs.","security":[{"bearerKey":[]}],"responses":{"200":{"description":"The programs."},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tax/calculations":{"post":{"operationId":"createTaxCalculation","tags":["Tax calculations"],"summary":"Run a deterministic tax calculation.","security":[{"bearerKey":[]}],"description":"Deterministic: the same request always returns the same lines. Send an Idempotency-Key to make retries safe; a replay carries `Idempotent-Replayed: true`.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jurisdiction","tax_year","inputs"],"properties":{"jurisdiction":{"type":"string","enum":["CA"]},"program":{"type":"string","enum":["T1","T2","1120","CT600","CIT"],"description":"Required for CA; defaults to the jurisdiction's program elsewhere."},"tax_year":{"type":"integer","minimum":2020,"maximum":2035},"inputs":{"oneOf":[{"title":"CA/T1","type":"object","required":["facts"],"properties":{"facts":{"type":"object","description":"Personal facts: province, dateOfBirth, maritalStatus, eligibleDependant, …"},"slips":{"type":"array","items":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["T4","T4A","T4A_OAS","T4A_P","T4E","T5","T3","T5008","T2202","RRSP_RECEIPT","T2125","T776"]}},"additionalProperties":true}},"claims":{"type":"object","description":"rrspDeduction, professionalDues, childCareExpenses, otherEmploymentExpenses, medicalExpenses, charitableDonations, studentLoanInterest as decimal strings."}},"description":"inputs = { facts, slips, claims } exactly as TaxPio's T1 rule package takes them: money as decimal strings in dollars, slips typed by kind (T4, T4A, T5, …)."}]}}}}}},"responses":{"201":{"description":"The calculation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Calculation"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"413","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"415","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"422","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listTaxCalculations","tags":["Tax calculations"],"summary":"List calculations, newest first.","security":[{"bearerKey":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"The previous page's next_cursor."}],"responses":{"200":{"description":"A page of calculations.","content":{"application/json":{"schema":{"type":"object","required":["data","has_more","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Calculation"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tax/calculations/{calculationId}":{"get":{"operationId":"getTaxCalculation","tags":["Tax calculations"],"summary":"Fetch one calculation.","security":[{"bearerKey":[]}],"parameters":[{"name":"calculationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The calculation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Calculation"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sandbox/scenarios":{"get":{"operationId":"listSandboxScenarios","tags":["Sandbox"],"summary":"Deterministic sandbox scenarios for every program and outcome.","description":"Sandbox keys only (tp_test_…). A live key receives 403 SANDBOX_ONLY.","security":[{"bearerKey":[]}],"responses":{"200":{"description":"The scenarios."},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sandbox/scenarios/{scenarioId}/run":{"post":{"operationId":"runSandboxScenario","tags":["Sandbox"],"summary":"Run a scenario as a real calculation in the sandbox.","security":[{"bearerKey":[]}],"parameters":[{"name":"scenarioId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"201":{"description":"The calculation, with the scenario it came from.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Calculation"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sandbox/webhook-sink/{endpointId}":{"post":{"operationId":"sandboxWebhookSink","tags":["Sandbox"],"summary":"A receiver on our host that verifies TaxPio's signature.","description":"Register a sandbox endpoint whose URL is https://api.taxpio.com/v1/sandbox/webhook-sink/{endpointId} (the id you get back) and every delivery lands here, is verified with your endpoint's secret, and shows in the trace.","security":[],"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Taxpio-Signature","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Received and verified."},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"413","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks":{"get":{"operationId":"listWebhookEndpoints","tags":["Webhooks"],"summary":"List webhook endpoints.","security":[{"bearerKey":[]}],"responses":{"200":{"description":"The endpoints.","content":{"application/json":{"schema":{"type":"object","required":["data","has_more","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createWebhookEndpoint","tags":["Webhooks"],"summary":"Register an endpoint; the signing secret is returned once.","security":[{"bearerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"https only; a public host, or the sandbox sink on api.taxpio.com."},"description":{"type":"string","maxLength":500},"events":{"type":"array","items":{"type":"string","enum":["calculation.completed","key.revoked","webhook.test"]},"description":"Defaults to every event."}}}}}},"responses":{"201":{"description":"The endpoint with its secret (shown once).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"type":"object","properties":{"secret":{"type":"string"}}}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"422","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{endpointId}":{"get":{"operationId":"getWebhookEndpoint","tags":["Webhooks"],"summary":"Fetch one endpoint.","security":[{"bearerKey":[]}],"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteWebhookEndpoint","tags":["Webhooks"],"summary":"Remove an endpoint and its deliveries.","security":[{"bearerKey":[]}],"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted."},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{endpointId}/test":{"post":{"operationId":"testWebhookEndpoint","tags":["Webhooks"],"summary":"Queue a webhook.test delivery.","security":[{"bearerKey":[]}],"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Queued; the runner delivers within half a minute."},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{endpointId}/deliveries":{"get":{"operationId":"listWebhookDeliveries","tags":["Webhooks"],"summary":"Recent deliveries to an endpoint.","security":[{"bearerKey":[]}],"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"The deliveries.","content":{"application/json":{"schema":{"type":"object","required":["data","has_more","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/connections":{"get":{"operationId":"listConnections","tags":["Connections"],"summary":"Connections to client profiles.","security":[{"bearerKey":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of connections.","content":{"application/json":{"schema":{"type":"object","required":["data","has_more","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Connection"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"inviteConnection","tags":["Connections"],"summary":"Invite a client to connect a profile.","description":"TaxPio emails the client a link; they choose which of their profiles to connect and which permissions to grant. The connection is INVITED until then, and can be revoked by either side.","security":[{"bearerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["client_email","system_name"],"properties":{"client_email":{"type":"string","format":"email"},"client_name":{"type":"string"},"category":{"type":"string","enum":["ACCOUNTING","ERP","ECOMMERCE","PAYROLL","PAYMENTS","CUSTOM"]},"system_name":{"type":"string","description":"The system the records come from, e.g. QuickBooks Online, Shopify, Gusto."},"permissions":{"type":"array","items":{"type":"string","enum":["records.import","records.read","documents.write"]},"description":"Defaults to all three."}}}}}},"responses":{"201":{"description":"The invited connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connection"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"422","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/connections/{connectionId}":{"get":{"operationId":"getConnection","tags":["Connections"],"summary":"Fetch one connection.","security":[{"bearerKey":[]}],"parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connection"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"revokeConnection","tags":["Connections"],"summary":"End a connection.","security":[{"bearerKey":[]}],"parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Revoked."},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/connections/{connectionId}/records":{"post":{"operationId":"importRecords","tags":["Connections"],"summary":"Push up to 500 records into the connected profile.","description":"Each record is identified by your external_id; a repeat of the same id is counted as a duplicate and never written twice. Amounts are signed decimal strings in the profile's currency: negative for money out, positive for money in. Records land as unreviewed transactions with receipt-match suggestions, exactly as a bank sync does.","security":[{"bearerKey":[]}],"parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["records"],"properties":{"records":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/RecordInput"}}}}}}},"responses":{"201":{"description":"The import summary: inserted, duplicates, suggestions, affected_tax_years."},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"422","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listRecords","tags":["Connections"],"summary":"Records this connection pushed.","security":[{"bearerKey":[]}],"parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of records."},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/connections/{connectionId}/documents":{"post":{"operationId":"uploadConnectionDocument","tags":["Connections"],"summary":"Upload a document into the connected profile.","description":"multipart/form-data with the file (PDF, JPEG, PNG or WebP, up to 15 MB) plus optional metadata; the vault's pipeline and AI suggestions run as for any capture.","security":[{"bearerKey":[]}],"parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":"The stored document."},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"413","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"422","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage":{"get":{"operationId":"getUsage","tags":["Usage and credits"],"summary":"Requests per day and operation.","security":[{"bearerKey":[]}],"parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Usage for the window (at most 92 days)."},"400":{"description":"400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/credits":{"get":{"operationId":"getCredits","tags":["Usage and credits"],"summary":"Credit balance and recent movements.","description":"Credits pay for billable filing actions on live keys and are consumed once per request (the request id is the idempotency key). A live call that needs more credits than the workspace holds answers 402 CREDITS_REQUIRED. Sandbox never bills.","security":[{"bearerKey":[]}],"responses":{"200":{"description":"The balance."},"401":{"description":"401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerKey":{"type":"http","scheme":"bearer","bearerFormat":"tp_live_… or tp_test_…","description":"Scopes: calculations:read, calculations:write, connections:manage, records:import, records:read, documents:read, documents:write, webhooks:manage, usage:read."}},"schemas":{"Error":{"type":"object","required":["error","code","requestId"],"properties":{"error":{"type":"string","description":"A sentence a person can read."},"code":{"type":"string","enum":["BAD_REQUEST","UNAUTHENTICATED","PAYMENT_REQUIRED","FORBIDDEN","NOT_FOUND","METHOD_NOT_ALLOWED","NOT_ACCEPTABLE","REQUEST_TIMEOUT","CONFLICT","GONE","PAYLOAD_TOO_LARGE","UNSUPPORTED_MEDIA_TYPE","VALIDATION_FAILED","LOCKED","PRECONDITION_REQUIRED","RATE_LIMITED","INTERNAL","NOT_IMPLEMENTED","UNAVAILABLE","TIMEOUT","ORIGIN_REQUIRED","PASSKEY_REQUIRED","PASSKEY_ENROLLMENT_REQUIRED","RECENT_MFA_REQUIRED","RECENT_AUTHENTICATION_REQUIRED","ACCOUNT_PASSWORD_REQUIRED","EMAIL_VERIFICATION_REQUIRED","VERIFICATION_DELIVERY_FAILED","RESOURCE_ROUTE_UNAVAILABLE","MALWARE_DETECTED","NONDETERMINISTIC_PROVIDER_RETRY","CREDITS_REQUIRED","API_KEY_MISSING","API_KEY_INVALID","API_KEY_REVOKED","API_KEY_EXPIRED","WORKSPACE_SUSPENDED","APPLICATION_ARCHIVED","SCOPE_REQUIRED","PRODUCTION_REVIEW_REQUIRED","IDEMPOTENCY_KEY_INVALID","IDEMPOTENCY_KEY_REUSED","IDEMPOTENCY_KEY_IN_PROGRESS","BODY_INVALID","UNSUPPORTED_PROGRAM","SANDBOX_ONLY","CONNECTION_PENDING","CONNECTION_REVOKED","CONNECTION_PERMISSION_REQUIRED","LIVE_ONLY","WEBHOOK_SIGNATURE_INVALID"],"description":"What a client branches on."},"requestId":{"type":"string","description":"Quote it to support; it is also the x-request-id response header."},"docs_url":{"type":"string","format":"uri"},"problems":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}},"Calculation":{"type":"object","required":["id","object","environment","jurisdiction","program","tax_year","rule_package","currency","scope","reasons","notes","lines","inputs","input_hash","created_at"],"properties":{"id":{"type":"string","pattern":"^calc_[A-Za-z0-9]{20,32}$"},"object":{"type":"string","enum":["tax.calculation"]},"environment":{"type":"string","enum":["live","sandbox"]},"jurisdiction":{"type":"string","enum":["CA"]},"program":{"type":"string","enum":["T1","T2"]},"tax_year":{"type":"integer"},"rule_package":{"type":"string","description":"The versioned rule package that produced the answer."},"currency":{"type":"string"},"scope":{"type":"string","enum":["IN_SCOPE","OUT_OF_SCOPE","INCOMPLETE"],"description":"OUT_OF_SCOPE: the inputs describe a case the package refuses, with reasons. INCOMPLETE: CA/T1 with blocking issues."},"reasons":{"type":"array","items":{"type":"string"}},"notes":{"type":"array","items":{"type":"string"}},"lines":{"type":"array","items":{"type":"object","required":["key","label"],"properties":{"key":{"type":"string"},"label":{"type":"string"},"amount_minor":{"type":"integer","description":"Minor units (cents, pence, kobo) for preview programs."},"amount":{"type":"string","description":"Decimal string in the currency for CA/T1."},"text":{"type":"string"}}}},"summary":{"type":"object","additionalProperties":{"type":"string"}},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"severity":{"type":"string"},"message":{"type":"string"},"fix_action":{"type":"string"}}}},"inputs":{"type":"object"},"input_hash":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["webhook_endpoint"]},"environment":{"type":"string","enum":["live","sandbox"]},"url":{"type":"string"},"description":{"type":"string","nullable":true},"events":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["ACTIVE","DISABLED"]},"secret_prefix":{"type":"string"},"consecutive_failures":{"type":"integer"},"last_delivery_at":{"type":"string","nullable":true},"created_at":{"type":"string"}}},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["webhook_delivery"]},"endpoint_id":{"type":"string"},"event_id":{"type":"string"},"event_type":{"type":"string"},"status":{"type":"string","enum":["PENDING","DELIVERED","FAILED","DEAD"]},"attempts":{"type":"integer"},"next_attempt_at":{"type":"string","nullable":true},"last_status":{"type":"integer","nullable":true},"last_error":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"created_at":{"type":"string"}}},"Event":{"type":"object","description":"The body of every webhook delivery, signed with `Taxpio-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">`.","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["event"]},"type":{"type":"string","enum":["calculation.completed","key.revoked","webhook.test"]},"created":{"type":"string"},"environment":{"type":"string"},"workspace_id":{"type":"string"},"data":{"type":"object"},"attempt":{"type":"integer"}}},"Connection":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["connection"]},"environment":{"type":"string"},"status":{"type":"string","enum":["INVITED","ACTIVE","REVOKED","DECLINED","EXPIRED"]},"category":{"type":"string"},"system_name":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"client_email":{"type":"string","nullable":true},"client_name":{"type":"string","nullable":true},"profile":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"granted_at":{"type":"string","nullable":true},"revoked_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"last_import_at":{"type":"string","nullable":true},"records_imported":{"type":"integer"},"documents_imported":{"type":"integer"},"created_at":{"type":"string"}}},"RecordInput":{"type":"object","required":["external_id","occurred_at","description","amount"],"properties":{"external_id":{"type":"string","maxLength":120,"description":"Your stable id for the record."},"occurred_at":{"type":"string","format":"date"},"description":{"type":"string","maxLength":240},"amount":{"type":"string","description":"Signed decimal string, at most two decimals, non-zero."},"counterparty":{"type":"string","maxLength":200,"description":"Folded into the description when the description does not already name it; TaxPio's own counterparty is set when the owner reviews the record."},"category":{"type":"string","maxLength":80,"description":"Kept as a hint in the import's audit trail; TaxPio's category and tax treatment are set when the owner reviews the record."}}},"Principal":{"type":"object","properties":{"object":{"type":"string","enum":["principal"]},"workspace":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"application":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"environment":{"type":"string","enum":["live","sandbox"]},"scopes":{"type":"array","items":{"type":"string","enum":["calculations:read","calculations:write","connections:manage","records:import","records:read","documents:read","documents:write","webhooks:manage","usage:read"]}},"rate_limit_per_minute":{"type":"integer"}}}}}}