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.

MethodPathReturns
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
// GET /api/products/{slug}/ { "id": 42, "title": "Leather backpack", "slug": "leather-backpack", "description": "...", "product_type": "physical", "price": "1490.00", "compare_at_price": null, "commission_rate": "8.00", "commission_display": "...", "category": {"id": 3, "name": "Accessories", "slug": "accessories", "product_type": "physical", "description": "..."}, "status": "approved", "view_count": 120, "created_at": "2026-09-01T10:00:00+02:00", "updated_at": "2026-09-20T08:30:00+02:00" }

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.

AreaPrefixExamples
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

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

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.

KeyDefault limit
Sandbox60 requests / minute
Live600 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.

import hashlib, hmac, time def verify(secret, header, body, tolerance=300): parts = dict(item.split("=", 1) for item in header.split(",")) t = int(parts["t"]) if abs(time.time() - t) > tolerance: return False expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, parts["v1"])

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.

{ "error": "insufficient_scope", "required_scope": "payments:read", "message": "This API key does not grant payments:read." }
StatusMeaning
400The request is invalid; message says why
401Missing, invalid or revoked API key
403insufficient_scope, or wrong_environment for a key used on the other environment
404Not found. Records that belong to another organisation are reported exactly like missing ones (a few payment endpoints answer 400 with a not-found error)
409The request conflicts with the record's current state
429rate_limited; wait for Retry-After seconds

Samples

Examples

curl: approved listings (no key)

curl https://taliosquare.international/api/products/

curl: your usage with a sandbox key

curl -H "X-API-Key: tsk_sandbox_..." \ https://taliosquare.international/sandbox/v1/usage/

Python: your workflow runs

import requests r = requests.get( "https://taliosquare.international/sandbox/v1/tmcp/runs/", headers={"X-API-Key": "tsk_sandbox_..."}, timeout=30, ) r.raise_for_status() for run in r.json()["results"]: print(run["workflow"], run["status"])
Keep keys out of source control and client-side code. If a key is exposed, revoke it at Developer keys (sandbox) or ask support (live).
TradeSafe Escrow
KYC Verified Sellers
Courier Guy · Fastway · Courier IT
Card Payments via TradeSafe