This guide gets you from "I have credentials" to "I'm making authenticated calls and getting data back" in about ten minutes. It covers the concepts you'll need long-term — auth, scopes, pagination, idempotency, errors — but doesn't list every endpoint. For the full endpoint catalog with request/response schemas and an interactive try-it console, see external-api.pirros.com/docs.

If you don't yet have credentials, your firm admin issues them — point them at Set up API access for your firm.

Two requests, in order.

1. Get an access token.

Response:

2. Use the token to list tags in a workspace.

Response:

If that worked, you're set. The rest of this guide explains what's actually happening and the patterns you'll see across other endpoints.

Every /v1/* success response uses this envelope: a top-level response object holding the payload (for lists, data + next_cursor + expanded), and a sibling meta object holding request_id. Parse body.response, not body.data.

Pirros uses OAuth 2.0 client-credentials flow. There are no user logins, no browser redirects, and no refresh tokens — just a server-to-server exchange of client ID + secret for a short-lived JWT.

Token lifetime: 1 hour. Cache the token until close to expiry, then request a new one. Pirros doesn't issue refresh tokens — you re-run the POST /oauth/token call.

Revoking access. If a credential is compromised, an admin revokes it from Settings → API Keys (Revoke, or Regenerate the secret). Revocation is immediate — the next API call with a token from that key fails 401 invalid_token. (There is no developer-side token-revocation call you need to make; access is controlled at the key level by the admin.)

Note on hosts. The OAuth token endpoint is served from {{TOKEN_HOST}}; all /v1/* content endpoints are served from external-api.pirros.com. (Confirm exact production hosts before final publication.)

All content endpoints are workspace-prefixed:

{workspaceId} is a workspace UUID and must match a workspace your credentials were granted access to.

How an inaccessible workspace/resource responds depends on the endpoint type:

Required header on every authenticated request:

Pirros echoes a request ID back on every response:

Include this ID in support tickets — it lets the Pirros team find your request in our logs. The same value appears in the body as meta.request_id.

Your credentials carry a list of scope grants. Each grant is the combination of a workspace, a filter, and an action (read / write / download). On each request, Pirros checks whether your credentials hold a grant matching the workspace in the URL, the resource type being accessed (families, details, stashes, tags), and the required action.

Your firm admin sets these up — see Resource filters: controlling what your API integrations can access for the concept.

What you'll see as a developer:

If you see this, ask the firm admin to broaden the grant — they can either add a wider system filter (e.g. default:details) or author a custom filter that matches what you're trying to access.

List endpoints use cursor-based pagination. Pass cursor and limit as query params:

Response (note the standard response / meta envelope — next_cursor is inside response, not at the top level):

To get the next page, pass response.next_cursor back as the cursor query param. When response.next_cursor is null, you've reached the end.

Default limit: 25. Max limit: 100. (A limit outside [1, 100] is rejected with 400 — it is not clamped.)

Exception: GET /v1/workspaces/{ws}/tags returns up to 500 tags in a single response with next_cursor: null — tag counts are capped, so paging isn't needed.

Write endpoints (POST /stashes, PATCH /stashes/{id}) accept an Idempotency-Key header. Include a unique value (a UUID is fine) on every write:

The create body is strict: name, project_id (UUID), and item_ids (detail_ids + family_ids arrays) are required; description and is_permanent are optional. Unknown fields are rejected with 400.

If your client retries (network blip, ambiguous timeout), Pirros recognizes the repeated key and returns the original response instead of creating a duplicate. Keys are remembered for 24 hours. Reusing a key with a different request body returns 409 IDEMPOTENCY_CONFLICT.

If you don't supply the header, every write is treated as new — a retry after an ambiguous timeout will create a duplicate stash. Always send the header on writes.

Download endpoints don't stream files directly. Instead, they return the standard {response, meta} envelope whose payload carries a download_url:

Response:

Fetch the file from response.download_url.

URL lifetime differs by file type:

Don't auto-follow redirects. The JSON wrapper is intentional — most HTTP clients can't authenticate against the signed S3 URL the same way they authenticate against Pirros, so we hand you the URL explicitly rather than redirecting.

The three download endpoints:

Most /v1/* responses use this envelope on failure:

/oauth/* endpoints follow RFC 6749's flat shape instead:

Common codes:

429 is the one exception to the /v1 error envelope. The rate limiter returns a flat body, not the { error: { code, message }, meta } shape: json { "error": "too_many_requests", "error_description": "Rate limit exceeded. Please retry after the indicated time.", "retry_after": 1234, "request_id": "8e1a3c4f-..." }

Always include request_id when you contact support — it's how we find your specific request in our logs.

When you hit a limit, Pirros returns 429 with a Retry-After header (in seconds). Wait that long before retrying.

Best practices:

For the full endpoint catalog — every route, every request schema, every response schema, plus an interactive try-it console — see external-api.pirros.com/docs.

What's covered in v1:

Endpoints not yet in v1 but planned: family upload, family history, detail flags, family references, family group.

If you hit a snag, contact [email protected]. Include:

We can trace requests by request_id and respond faster when you include it.