For Developers
API Documentation
Two APIs are available at https://taliosquare.international: the public, read-only Talio Square catalogue API, and the key-based Talio API (v1) for payments, logistics, media, AI, workflows, security and systems.
Public, read-only
Talio Square catalogue API
JSON over HTTPS under /api/. No key is needed. Only approved listings, active categories and approved, active businesses are returned. Lists are returned whole as JSON arrays; there is no pagination.
| Method | Path | Returns |
|---|---|---|
| GET | /api/ | Index of the endpoints below |
| GET | /api/products//api/products/{slug}/ | Approved listings; one listing by slug |
| GET | /api/categories//api/categories/{slug}/ | Active categories; one category by slug |
| GET | /api/vendors//api/vendors/{store_slug}/ | Approved, active businesses; one business by its slug |
| GET | /api/hot/ | Up to 24 approved listings, most viewed first |
| GET | /api/new/ | Up to 24 approved listings, newest first |
| GET | /api/featured-stores/ | Up to 12 approved, active businesses in random order |
| GET | /api/orders//api/orders/{order_number}/ | The signed-in buyer's own orders. Uses the Talio Square sign-in session (browser); there are no keys for this API |
Key-based
Talio API (v1)
Versioned under /v1/. Every request sends an API key in the X-API-Key header. Each key belongs to one organisation and sees only that organisation's records: another organisation's record answers as not found.
Full reference: OpenAPI
GET /v1/openapi.json is the complete OpenAPI 3.1 description of this API, generated from the running code. It lists every operation, its path parameters and the scope it requires (x-talio-required-scope). The main operations also carry field-level request and response schemas, which Talio's contract tests check against the live code. No key is needed to read it.
| Area | Prefix | Examples |
|---|---|---|
| Payments (TSP) — escrow held by the escrow provider, never by Talio | /v1/payments/ | Payment status, disputes, ledger, reconciliation of Talio's figures against the provider's |
| Logistics (TSL) | /v1/logistics/ | Shipments; a tracking timeline per shipment (carrier scans you record, and polling only where a carrier's tracking is available, today the sandbox's simulated carrier); collections with labels (held as restricted media); delivery evidence and exceptions; cost reconciliation |
| Media (TSM) | /v1/tsm/media/ | Asset metadata and files, legal hold |
| AI (TCI) | /v1/ai/ | Generation, your execution log, your monthly execution cap (/v1/ai/quota/) |
| Workflows (TMCP) | /v1/tmcp/ | Governed workflows with approvals |
| Security (TSSec) | /v1/security/ | Reporting security events; findings; signed attestations (ledger integrity, open high findings, tested restores) |
| Systems (TSSys) | /v1/systems/ | Resources, drift, backups and restore tests; declarative configuration (plan and apply a manifest) |
| Your account | /v1/usage/, /v1/webhooks/ | Usage, webhook endpoints |
Access
Keys: Sandbox and Live
Keys look like tsk_<environment>_<id>.<secret>. The full key is shown once, when it is created; Talio stores only a hash of it. Keys can be revoked at any time.
Sandbox keys: self-serve, isolated
Create up to five sandbox keys yourself at Developer keys (sign in first). Sandbox keys work only on the sandbox API at https://taliosquare.international/sandbox/v1/, a separate environment with its own data. There you can read and write: payments go to the escrow providers' sandboxes, carrier rates and AI output are simulated, and nothing reaches live data or live providers. The shared identity endpoints are not available in the sandbox. Sandbox keys are limited to 60 requests a minute.
Live keys: issued by Talio
Live keys are issued by Talio after review, with the scopes your integration needs, and work only on the live API at https://taliosquare.international/v1/. Contact support to apply. Live keys default to 600 requests a minute.
A key used on the other environment is refused with 403 wrong_environment, naming the right address. Every response, and every webhook delivery, carries a Talio-Environment header (live or sandbox).
Permissions
Scopes
A key carries scopes such as payments:read or logistics:write. Reads (GET) need <area>:read; other methods need <area>:write; <area>:* grants both. Webhook endpoints need webhooks:manage, and approving a workflow step needs tmcp:approve. A call without the required scope is refused with 403 insufficient_scope, naming the scope in required_scope.
Policy
Rate Limits & Usage
Limits are per key, per minute. Accepted requests carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds). Over the limit, the API answers 429 rate_limited with a Retry-After header.
| Key | Default limit |
|---|---|
| Sandbox | 60 requests / minute |
| Live | 600 requests / minute (can be set per key) |
GET /v1/usage/?from=YYYY-MM-DD&to=YYYY-MM-DD returns your key's own requests per day and per area, for up to 92 days.
Plans and billing. GET /v1/plans/ lists plans with published prices (no key needed). With billing:read, GET /v1/billing/subscriptions/ returns your organisation's plans and GET /v1/billing/records/ its monthly statements: requests per area, escrow released, and amounts where the plan is priced. Developer keys shows the same for your organisation.
Events
Webhooks
Register an HTTPS endpoint on a public host with POST /v1/webhooks/endpoints/ and {"url": "...", "events": [...]} (use "*" for all). The response includes the endpoint's signing secret, shown once. You receive events only for your own organisation's records. Failed deliveries are retried with exponential backoff, up to six attempts.
| Events |
|---|
payment.held payment.released payment.refunded payment.cancelled payment.failed payment.disputed payment.dispute_resolved |
shipment.dispatched shipment.delivered shipment.returned shipment.exception shipment.exception_resolved shipment.collection_booked shipment.tracking_updated |
workflow.approval_required workflow.approval_overdue |
Verifying a delivery
Each delivery carries Talio-Signature: t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of "<t>." + raw body with your endpoint's secret. Compare in constant time, and reject old timestamps.
Governance
Workflows and approvals
Actions with consequences, such as releasing escrow or resolving a dispute, run as workflows under /v1/tmcp/. Start one with POST /v1/tmcp/runs/; send an Idempotency-Key header so a retried request returns the same run. A step that moves money pauses until a different key holding tmcp:approve approves it; the key that started a run cannot approve it. A step that fails is retried a bounded number of times, and completed steps are undone in reverse order where they can be. Every run keeps a complete, append-only event log at GET /v1/tmcp/runs/{run_id}/. When a step waits for approval you receive workflow.approval_required, and workflow.approval_overdue if it waits too long. GET /v1/tmcp/workflows/ lists the available workflows and their inputs. In the sandbox you can run the same workflows against sandbox data, approving with a second sandbox key.
Handling
Errors
Talio API errors are JSON with a machine-readable error code and a message.
| Status | Meaning |
|---|---|
| 400 | The request is invalid; message says why |
| 401 | Missing, invalid or revoked API key |
| 403 | insufficient_scope, or wrong_environment for a key used on the other environment |
| 404 | Not found. Records that belong to another organisation are reported exactly like missing ones (a few payment endpoints answer 400 with a not-found error) |
| 409 | The request conflicts with the record's current state |
| 429 | rate_limited; wait for Retry-After seconds |
Samples