API reference

Base URL

Every request goes to https://server.tabbio.com. The consent screen is the one exception: it is a browser page on https://app.tabbio.com/oauth/authorize, because a person has to see it.

Point a standard OAuth client at https://server.tabbio.com/.well-known/oauth-authorization-server and every endpoint below is configured for you.

Response envelope

Every JSON response carries the same three keys. Read data on success and error on failure. meta holds paging information on list endpoints and is null elsewhere.

{
  "data": { "id": "usr_2f8a", "name": "Sara Ahmed" },
  "error": null,
  "meta": null
}

{
  "data": null,
  "error": {
    "code": "OAUTH_INSUFFICIENT_SCOPE",
    "message": "This token does not carry the cv:read scope."
  },
  "meta": null
}

Four things are deliberately not wrapped: POST /oauth/token and POST /oauth/introspect, which answer the flat bodies RFC 6749 and RFC 7662 define, the discovery document, where RFC 8414 does, and the PDF endpoints, which stream a file. POST /oauth/revoke keeps the envelope, because RFC 7009 specifies no success body of its own. The field tables on the endpoint pages already show the unwrapped shape, so what you read there is what sits inside data.

Pagination

Every list endpoint is page based. Pass page (1 based, defaults to 1) and pageSize (1 to 100, defaults to 25). There are no cursors anywhere in this API.

{
  "data": [ /* one page of records */ ],
  "error": null,
  "meta": { "page": 1, "pageSize": 25, "total": 63, "totalPages": 3 }
}

Stop when page reaches totalPages, or when a page comes back shorter than pageSize. Records are ordered newest first, so a job posted while you are paging shifts later records by one; if you are reconciling rather than browsing, key on the record id rather than the position.

Authentication

Both schemes are HTTP bearer tokens. Which one you use depends on whether a person is involved.

User access token

A user access token (`tbo_at_...`) obtained through Sign in with Tabbio. Send it as `Authorization: Bearer <token>`.

Authorization: Bearer tbo_at_5Kd9xQ2mVr7tN0pLzY4bHwR3jS8cF1gU

API key

A server-to-server API key (`tbo_sk_...`) created in Tabbio under Settings, Developer. Send it as `Authorization: Bearer <key>`. Available scopes: `companies:read`, `companies:write`, `jobs:read`, `jobs:write`, `candidates:read`.

Authorization: Bearer tbo_sk_9Fh3xK7mQr2tV0nLzB6yWd4Sc8Jg1Up5Rt7

Every credential is prefixed, which is what lets a secret scanner recognise one in a commit.

Scopes

A user grants scopes on the consent screen. They may grant fewer than you asked for, so read the scope field on the token response rather than assuming you got what you requested.

API keys carry company scopes instead. They are chosen when you create the key and never change.

Errors

The code is stable and safe to branch on. The message is written for a human reading a log and can change at any time.

The errors guide covers what to do about each one.

Rate limits

Over the limit answers 429. Back off and retry: a burst limit clears within seconds. Partner API calls are counted against your app, so every key you own shares one budget; user token calls are counted against the connection; and the OAuth endpoints are counted against your client id, falling back to the client IP when a request names no client.

Versioning

The partner API is versioned in the path. Everything under /v1 keeps its shape: fields are added, never removed or retyped, and a new field can appear in a response at any time, so parse leniently. A change that would break a client ships as /v2 alongside /v1.

This page describes version 2.0.0 of the document. https://server.tabbio.com/v1/openapi.json serves the live version, which is what an SDK generator or a coding agent should read.

OAuth endpoints are not versioned, because they implement published standards rather than a Tabbio shape.

Endpoints