Build on your AgentOS data

The REST API and the SDK give your code the same data your agents and your team work on: modules, spaces, records, fields, statuses, labels and files. Every system has its own address, and every request carries a token. The ACT automations your agents write use the same Python SDK.

Which way in fits my work?

All three reach the same data, with the same permissions.

How do I make my first request?

1. Create an API token: click your avatar, then API & MCP tokens > New API/MCP token > API Token. See API and MCP tokens.
2. Call the API with the token:

curl https://<system name>.boost.space/api/space \
  -H "Authorization: Bearer $BOOST_SPACE_TOKEN"

<system name> is the name in your AgentOS address: for https://acme.boost.space it is acme. The answer lists the spaces of your system as JSON.

What are the basics?

How do I authenticate?

With a token for your own scripts and integrations. It works as you, with the permissions you chose for it, and never more than you have. See API and MCP tokens.

With OAuth 2.0 for an app that acts for other people. Register the app with POST /auth/oauth/client (a name and up to five HTTPS redirect addresses), then run the authorization code flow:

1. Send the person to GET /auth/oauth/authorize with response_type=code, your client_id and redirect_uri.
2. Exchange the code at POST /auth/oauth/token with grant_type=authorization_code. The answer holds an access_token, a refresh_token and expires_in.
3. Before the access token expires, get a new pair with grant_type=refresh_token.

Send the access token as a Bearer token, like any other.

What can I reach?

The API reference describes every public endpoint, with its parameters, schemas and code samples.

How do I read records?

List a module's records, newest first, 50 at a time:

curl -G "https://<system name>.boost.space/api/module/<module id>/item" \
  -H "Authorization: Bearer $BOOST_SPACE_TOKEN" \
  --data-urlencode "order=id;DESC" \
  -d limit=50 -d offset=0

GET /record lists records across modules the same way, and GET /record/{recordId} reads one.

How do I filter?

Add filter=field operator value. Join conditions with ; or & for AND, and | for OR. Group them with parentheses.

For several values of one field, write status=(active|pending). A combined example: filter=(status=active|status=pending)&spaceId=5.

How do I page and sort?

• Paging: offset is the position of the first record, from 0, and limit the number of records. offset=20&limit=10 returns records 21 to 30.
• Counts: the X-BoostSpace-TotalRecords header holds the number of records that match. The X-BoostSpace-FoundRecords header holds the number in this answer.
• Sorting: order=field;ASC or order=field;DESC. Sort by several fields with commas: order=id;ASC,name;DESC. Without a direction, the order is DESC.

How do I write records?

Field values go in customFieldsValues. To have AgentOS map a payload from another system onto the fields, send it whole as rawPayload. Explicit fields win over the mapped ones.

Writes respect the token's priority: data from a source with a higher priority stays.

How do I keep a copy in sync?

Ask only for what changed. Add updatedSince=<Unix timestamp> to GET /record for records changed since then, and to GET /record/deleted for the IDs of records deleted since then.

What does an error look like?

Every 4xx and 5xx answer has the same JSON body:

{ "code": 4005, "message": "Object not found: Contact 123" }

code is the HTTP status, or a finer number: 4002 a missing required field, 4005 an object that was not found, 4031 two-factor authentication required, 4032 every field of the write was held back by token priority.

Can another app start an automation?

Yes, with a webhook. An ACT automation with an incoming webhook has its own address, and any app starts it with a POST:

curl -X POST "https://<system name>.boost.space/api/hook/<token>" \
  -H "Content-Type: application/json" \
  -d '{"orderId": 1042}'

The token in the address is the credential, so no Authorization header is needed. The body can be up to 1 MB of UTF-8, and the answer comes at once while the automation runs afterwards. When a webhook already holds its full queue of unfinished deliveries, it answers 429 with a Retry-After header. See Triggers and webhooks.

How do I start with the SDK?

Install it:

npm install @boost-space/sdk    # TypeScript
pip install boostspace-sdk      # Python

Then list your spaces:

import { BoostSpace } from "@boost-space/sdk";
const bs = new BoostSpace({ token: process.env.BOOST_SPACE_TOKEN!, system: "acme" });
for await (const space of bs.spaces.list({ order: "name;ASC" })) console.log(space.id);

from boostspace import BoostSpace
bs = BoostSpace("<your token>", system="acme")
for space in bs.spaces.list(order="name;ASC"):
    print(space.id)

The SDK pages through the results for you. See SDK.

Next: the API reference, or API and MCP tokens.