Use your base from a calendar or a script

A calendar link is a private address of one calendar view, for a calendar app such as Google Calendar, Apple Calendar or Outlook. The calendar app shows what you see in that view, without signing in.

1. Open a calendar view, one for everyone or your own, such as Deliveries under Orders in the example shop, and click Calendar link.
2. The box warns: "Anyone with the link sees what you see in this view, without signing in." Click Create link.
3. The link shows once. Click the copy button, then Done; it is not shown again.
4. In your calendar app, add it as a calendar you subscribe to by its address: in Google Calendar, Other calendars, From URL; in Apple Calendar, File, New Calendar Subscription; in Outlook, Add calendar, Subscribe from web.

Revoke a calendar link

Your calendar links are in Settings, API tokens, under Calendar links, each with its view's name and its base, the links of every base of yours in one list. Click the bin beside one, Revoke, then Revoke link, and the calendars that subscribe to it stop updating at once.

Limits and details

• You may have up to 20 calendar links in each base.
• The calendar holds the view's items as you see them, under your role and the view's filters, from 90 days ago on, up to 1,000.
• On a Date field an item is an all-day event, on a Date & time field an hour-long one; each event carries the view's columns you may see and a link to the item.
• The calendar is read again each time your calendar app fetches it, which each calendar app does on its own schedule, some only every few hours: an item moved out of the view leaves the calendar then.

A script of your own, such as a nightly export, uses your base through its API with an API token, sent as Authorization: Bearer <token>. The script works as you, under your role, and may do what you may do in the base:

• work with items, as you do in their lists and on their pages, and run their buttons. A change a row rule does not allow is refused with the rule's note, as on the item's page. A comment you wrote on an item, you change with PATCH /api/tables/<table>/items/<id>/comments/<comment> and its new text, and delete with DELETE on the same address; another user's comment, an agent's or one that came in by mail is refused;
• if you build the base, the work of Builder: its tables, automations and saved replies and its versions, and its code: the code's last runs at GET /api/tables/<table>/code/runs and a try on one item, where nothing is saved or sent, at POST /api/tables/<table>/code/test; if you are an admin, also its roles, its users and an export of all its data; if you manage the AI, its agents. What your role does not reach is refused, as in the browser;
• chat with the assistant or an agent, and read an item's chats;
• read your Inbox with GET /api/me/inbox (See everything open for you in the Inbox), and search as Search does: GET /api/search?q= finds the items of your lists, and GET /api/search?q=&only=shared your notifications, the mail, the channels, the messages and the files you may see, each with the path that opens it;
• change your name and your picture. The picture is yours as a user, so it changes in every base where you have a role.

What a script changes shows under your name, "via API".

Name a referenced item by a field

In a request of the API, a reference can name its item by a field no two items share instead of its id, such as "customer": {"email": "[email protected]"}. An email no customer has is refused with "No customer with that email".

Read the API's description (OpenAPI)

Your base describes its API in an OpenAPI document at https://<your base's address>/api/openapi.json: its tables, the fields of each, the routes of their items and their buttons. A developer or an AI client reads it to call the API without guessing. It shows only what the token's user may see and do, under that user's role.

Send a change only once (Idempotency-Key)

A script that sends a POST again after a lost answer, such as after a timeout, can make the same item two times. To stop this, send the header Idempotency-Key with a key of your own for each change, such as the number of the order, from 1 to 255 printable characters:

curl -X POST https://<your base's address>/api/tables/<table>/items \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1042' \
  -d '{"data": {...}}'

• The header is optional.
• If you send the same key with the same request again, the base writes nothing and gives the first answer again, with the header Idempotent-Replayed: true.
• If you send the same key with another request, the base refuses it with a 422 and writes nothing.
• A request that failed keeps no key, so you can send it again with the same key.
• Each key is yours only, and the base keeps it 24 hours.

Limits and details

• A token never signs in, and never changes your password, two-factor sign-in, sessions or email address, makes API tokens or calendar links, or views the base as someone else: those stay in your browser.
• A token for one base reaches that base alone; a token of all your bases reaches each of them, under your role in each (Make an API token for a program).
• A token does not copy or delete bases, or accept an invitation, and it creates a base only when you made it for all your bases with It can create bases: you accept an invitation at www.basecaptain.com (Open, add and switch between your bases), and an owner copies or deletes a base in its Settings (Copy a base).
• A script may make a temporary base with no token (Make a temporary base from a script).

The Builder API changes a base's tables, views, automations and other parts from a script, with the API token of a user whose role builds the base. Each path below is on your base's address, with the header Authorization: Bearer <token>.

1. Read the spec with GET /api/builder/spec. It gives the base's parts and its version: {"version": 7, "spec": {...}}.
2. Send the change to POST /api/builder/preview: the version you read and the ops, the steps of the change. The answer says what the change does, such as the values it removes, and nothing changes.
3. Send the same body to POST /api/builder/apply. The answer gives the new version: {"journal": "<journal id>", "version": 8}.

This change hides the field Notes from the lists of a table and removes its field Fax:

curl -X POST https://<your base's address>/api/builder/apply \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"version": 7, "ops": [{"op": "patch_table", "id": "<table id>",
       "fields": {"notes": {"actions": {"list": "hidden"}}, "fax": null}}]}'

• put_table sends a whole table, new or changed, as GET /api/builder/spec gives one, its actions included.
• patch_table changes part of a table: table holds only the table's keys to change, and fields holds the fields by key, the keys to change of each, null to remove one, or a whole new field.
• The other ops put or delete one part each, such as put_view, put_automation and delete_view. A put sends the whole part, as the spec gives it.

See and restore the versions

GET /api/builder/versions lists the versions of the base, newest first. The latest schema change shows "restore": true for an hour after it.

POST /api/builder/versions/<number>/restore puts back the base as it was just before that version, at once, with no confirmation. It undoes that version and every version after it, and the data written since is lost. Read the versions first.

GET /api/builder/journal lists each change, restore and export with its steps, newest first, and GET /api/builder/journal/<id> gives one.

Run a schedule, undo a change, print an item

• POST /api/schedules/<automation id>/run runs a schedule automation now, once, as Run now does. The next run stays when it was.
• POST /api/undo/<group> undoes a group of changes to items, such as an import, as Undo does. GET /api/history lists the groups. Add ?table=<table>&item=<id> to undo only one item of the group.
• GET /api/tables/<table>/items/<id>/print/<template> gives the page of a print template for one item, as HTML.

Limits and details

• A change with an old version, or with none, is refused with "The base changed since you loaded it": read the spec again, then send the change again.
• A key the change does not know is refused with its place, such as Unknown key "formula" in ops/0/table/fields/2/props, and a value of the wrong type with its key, such as Invalid value of ops/0/table/fields/2/required in the request body.
• An op your role does not reach is refused, as in the browser: roles and who sees what are an admin's, agents an AI manager's.
• The base's description of its API (/api/openapi.json) holds its tables and items, not the Builder API.