Back to home

Developers

Taply API

Taply exposes an HTTP API at https://api.gettaply.com, documented with OpenAPI 3.1. It currently covers the profiles, links, media and cards side of Taply: create a profile, publish it, manage its links and resolve a physical card. Responses are JSON and the spec is generated from the same code that serves the requests. Agent configuration, channels and conversations have no public surface yet — they are managed from the dashboard. When they ship, they will be announced here.

What the API offers

The resources the specification publishes today are grouped like this:

  • Identity and onboarding — sync the caller and read its state (GET /v1/me), and create, read, update and complete onboarding sessions.
  • Profiles — create, list, read and update profiles, check and change their slug, and publish or unpublish them.
  • Links — create, list, update, delete and reorder the links on a profile you own.
  • Media — upload image bytes, list them, read them, delete them and attach them to a profile, avatar included.
  • Destinations and cards — manage destinations and the physical cards that point to them, claimed with a single-use code.
  • Analytics — read aggregated link clicks and visits for a profile or a card the caller owns.
  • Public endpoints — read a published profile by slug, resolve a card public code, transformed media, and a sitemap of published profiles.

The authoritative list — with parameters, response schemas and error codes for every operation — is always the specification, not this page. If anything diverges, the specification wins.

OpenAPI specification

The OpenAPI 3.1 document is served at https://api.gettaply.com/openapi.json. It is public, needs no authentication and is generated from the same code that serves the requests, so it cannot fall out of date with the deployed implementation. You can hand it straight to a client generator, to Postman or to an agent that needs to discover the available operations.

First call (no credentials)

GET /health is public and takes no authentication. It is the fastest way to check connectivity and the state of the subsystems the API depends on:

curl -s https://api.gettaply.com/health

Response:

{
  "status": "ok",
  "checks": {
    "d1": "ok",
    "auth": "ok",
    "access": "ok",
    "kv": "ok",
    "r2": "ok",
    "mediaSourceSigning": "ok",
    "claimCodeHmac": "ok"
  }
}

It returns 200 when every required subsystem is ready and 503 with "status": "degraded" when one of them is not. You can try it in the browser: https://api.gettaply.com/health.

Authentication

Routes under /v1 that operate on an account's data require a Bearer token in the Authorization header. The token is the account holder's session, issued as a JWT by the authentication provider (Stytch), and it is validated locally on every request.

curl -s https://api.gettaply.com/v1/me \
  -H "Authorization: Bearer $TAPLY_TOKEN"

The API is multi-tenant: the token determines the account, and every operation resolves against the resources that account owns. Asking for someone else's resource never returns another business's data. Endpoints under /v1/public/ carry no token because they serve already published content, and the ones under /v1/internal/ use an operator principal separate from the holder's token: they are not part of the public surface.

Errors and traceability

Every error shares the same JSON shape, with a stable code meant for branching in code and a message meant to be read:

{
  "error": {
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header",
    "requestId": "2ba3ea27-e342-4abc-92a2-41fa595fd57a"
  }
}

The requestId field matches the x-request-id response header, which is present on every response, successful ones included. Keep it: it is what lets us find a specific request in the logs. If you report a failure, include it. Some errors add a details field with context specific to the operation.

Versioning & deprecation policy

Versioning is by URL. Every business route lives under the /v1 prefix. The service routes — /health and /openapi.json — are deliberately unversioned: they describe the API, not the domain.

  • Compatible changes within /v1: new optional fields in responses, new endpoints, new values in extensible enumerations. Your client must ignore fields it does not know; we do not treat them as breaking changes.
  • Breaking changes — removing or renaming a field, changing its type, tightening a validation, retiring an endpoint — are not made on /v1. They go to a new URL version (/v2), and /v1 keeps serving its contract.
  • Deprecations: when an operation becomes obsolete it will be announced on this page and marked as deprecated in the OpenAPI specification. Responses from that operation will carry the Deprecation header and, once a removal date is set, Sunset with that date (RFC 9745 and RFC 8594), plus a Link to the replacement when there is one.
  • Window: an operation announced as obsolete will keep responding at least until the date published in its Sunset header. No operation is ever retired without being announced this way first.

As of today no operation is deprecated: everything in the specification is current. When that changes, this section will list what is obsolete, from when, how long it keeps responding and what replaces it.

Rate limiting

The API is protected against abuse at the platform level. Per-account limits are not documented as a public contract yet, which is why we publish no figures here: promising a number we cannot hold is worse than not giving one.

Here is the commitment: once the limits are published, they will be exposed with the standard RateLimit and RateLimit-Policy headers (IETF RateLimit header fields for HTTP), so a client can read how much of its allowance is left and when it resets without guessing. A request rejected for going over will answer 429 with the same error shape as above and a Retry-After header. This section will be updated with the actual figures and the date they apply from.

In the meantime, the practical advice: retry with exponential backoff on 429 and 503, do not poll aggressively and reuse connections.

Support

Questions about the API, integrations or behavior that does not match the specification: contact@gettaply.com, with the endpoint, what you expected and the x-request-id from the response. For context on the product, about Taply; for the terms of use, the terms.