List categories

Returns the category tree flattened, in the order ThinkOut displays it: inflows first, then outflows, and within each direction every root followed immediately by its own children. Siblings follow position.

Reading the page top to bottom therefore gives the product’s own category screen. direction narrows to one of its two panels. Rebuild the hierarchy with parent_id, and re-sort with position within each parent_id if you need the order again after storing the rows.

The tree is exactly two levels deep. A category with a parent_id never has children of its own, and both levels can appear on a transaction.

A child’s direction and activity always match its root’s.

GET

categories

List categories

curl --request GET \
  --url https://api.thinkout.io/v1/categories \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.thinkout.io/v1/categories', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "object": "list",
  "data": [
    {
      "object": "category",
      "id": "3b4c5d6e-7f80-4a1b-9c2d-3e4f5a6b7c8d",
      "name": "Telecom",
      "code": null,
      "direction": "outflow",
      "activity": "operating",
      "parent_id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
      "position": 2,
      "color": "#1b7fe4",
      "created_at": "2024-01-01T10:00:00Z",
      "updated_at": "2024-01-01T10:00:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "<string>"
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_parameter",
    "message": "Parameter 'from' must be a date in YYYY-MM-DD format.",
    "param": "from",
    "request_id": "req_01J8ZT4Q7Y6M3K"
  }
}

{
  "error": {
    "type": "authentication",
    "code": "unauthorized",
    "message": "Invalid API key.",
    "param": null,
    "request_id": "req_01J8ZT4Q7Y6M3K"
  }
}

{
  "error": {
    "type": "rate_limit",
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "param": null,
    "request_id": "req_01J8ZT4Q7Y6M3K"
  }
}

Authorizations

Authorization

string

header

required

A workspace API key created in ThinkOut settings. One key reads one workspace.

Query Parameters

direction

enum<string>

Whether money comes in or goes out.

On a transaction or a forecast it follows the sign of amount and can never disagree with it. It is present so that responses can be grouped and read without inspecting signs.

Available options:

inflow,

outflow

limit

integer

default:100

Page size.

Required range: 1 <= x <= 500

cursor

string

Opaque token from the previous page's next_cursor.

Response

A page of categories.

object

string

required

Allowed value: "list"

data

object[]

required

Show child attributes

has_more

boolean

required

Whether another page exists.

next_cursor

string | null

required

Pass as cursor to fetch the next page. null on the last page.

⌘I

List categories

curl --request GET \
  --url https://api.thinkout.io/v1/categories \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.thinkout.io/v1/categories', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "object": "list",
  "data": [
    {
      "object": "category",
      "id": "3b4c5d6e-7f80-4a1b-9c2d-3e4f5a6b7c8d",
      "name": "Telecom",
      "code": null,
      "direction": "outflow",
      "activity": "operating",
      "parent_id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
      "position": 2,
      "color": "#1b7fe4",
      "created_at": "2024-01-01T10:00:00Z",
      "updated_at": "2024-01-01T10:00:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "<string>"
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_parameter",
    "message": "Parameter 'from' must be a date in YYYY-MM-DD format.",
    "param": "from",
    "request_id": "req_01J8ZT4Q7Y6M3K"
  }
}

{
  "error": {
    "type": "authentication",
    "code": "unauthorized",
    "message": "Invalid API key.",
    "param": null,
    "request_id": "req_01J8ZT4Q7Y6M3K"
  }
}

{
  "error": {
    "type": "rate_limit",
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "param": null,
    "request_id": "req_01J8ZT4Q7Y6M3K"
  }
}

Getting started

Working with data

MCP

API reference

List categories

Authorizations

Query Parameters

Response