API

Audit log

Read and export the workspace's record of who did what, and when.

Every change in the workspace is recorded as an audit entry: who acted (actorType, actorId), what they did (action, such as member.role.set), what it was done to (targetType, targetId), and details in meta. Entries cannot be changed.

Both calls take a range of whole UTC days, from to to, both included, covering at most 366 days. audit.range pages through it as JSON, oldest first; audit.export downloads it as one CSV or JSON file of up to 50,000 entries. Each export is itself recorded as audit.export. Both need the plan's audit log export feature and audit.read, which Owners and Admins have.

The audit log for a range of days, as a CSV or JSON file

GET /audit/export audit.export

Downloads every audit entry in a range of days as one file. from and to are UTC days, both included, covering at most 366 days; a range that is not, or that ends before it starts, answers 400 bad_range. Entries are oldest first. A range holding more than 50,000 entries answers 422 too_many_entries (details.total says how many it holds); export it in parts.

Entries written while the file is being sent are not in it. Each export is itself recorded in the audit log as audit.export. CSV columns: created_at (ISO 8601), action, actor_type, actor_id, target_type, target_id, meta (JSON), id. A cell a spreadsheet would run as a formula (one starting with =, +, -, @, a tab or a carriage return) starts with ' so it opens as text.

JSON is an object with from, to and entries, each entry as audit.range gives it. Needs the auditExport plan feature; without it the call answers 402 plan_required.

Scopes
audit.read
Plan
Audit log export, on Enterprise

Query parameters

NameTypeDescription
from required string The first day of the range, as YYYY-MM-DD in UTC. Matches ^\d{4}-\d{2}-\d{2}$.
to required string The last day of the range, as YYYY-MM-DD in UTC. It is included. Matches ^\d{4}-\d{2}-\d{2}$.
format string The file's format: csv or json. Default csv. One of csv, json. Default csv.

Response

200 OK. The file itself, with its own Content-Type. A refusal is a JSON error, as everywhere else.

Example request

curl "https://api.flipbird.io/api/v1/audit/export?from=string&to=string" \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -OJ

The audit log for a range of days, oldest first, a page at a time

GET /audit/range audit.range

The entries audit.export would carry, as JSON a page at a time. from and to are UTC days, both included, covering at most 366 days; a range that is not, or that ends before it starts, answers 400 bad_range. Entries are oldest first. total is how many entries the range holds. Pass nextCursor back as cursor, with the same from and to, for the next page.

It is null once a page holds fewer than limit entries, so the last page can be empty. A cursor this listing did not give answers 400 bad_cursor. The first page of a range (no cursor) is recorded in the audit log as audit.export. Needs the auditExport plan feature; without it the call answers 402 plan_required.

Scopes
audit.read
Plan
Audit log export, on Enterprise
MCP tool
audit_export

Query parameters

NameTypeDescription
from required string The first day of the range, as YYYY-MM-DD in UTC. Matches ^\d{4}-\d{2}-\d{2}$.
to required string The last day of the range, as YYYY-MM-DD in UTC. It is included. Matches ^\d{4}-\d{2}-\d{2}$.
cursor string The nextCursor of the previous page. Omit it for the first page. At most 200 characters.
limit integer Most entries in a page. Default 200. 1 to 1,000.

Response

200 OK. A JSON object:

Response fields (13)
NameTypeDescription
from string The first day of the range, as asked. Matches ^\d{4}-\d{2}-\d{2}$.
to string The last day of the range, as asked. Matches ^\d{4}-\d{2}-\d{2}$.
total integer How many entries the whole range holds, across every page.
entries array of objects This page's entries, oldest first.
entries[].id string The entry's id.
entries[].actorType string Who acted: user (a member, signed in), api_key (an API key), oauth (a connected app), system (Flipbird itself, such as a Stripe update or a scheduled task) or superadmin (Flipbird staff using support access).
entries[].actorId string Who acted, by actorType: a user id, an API key's id, a connected app's grant id or a staff member's id. For system, the name of the process (such as stripe) or null. Can be null.
entries[].action string What was done, as dotted lowercase words such as member.role.set or invite.create.
entries[].targetType string The kind of thing acted on, such as user, document, folder or webhook_endpoint; null when there is none. Can be null.
entries[].targetId string The id of the thing acted on (for a folder, its path); null when there is none. Can be null.
entries[].meta map of anys Details that depend on the action, such as a role's old and new values. Empty when there are none.
entries[].createdAt number When it happened, in epoch milliseconds.
nextCursor string Pass it as cursor for the next page; null when the range is done. Can be null.

Example request

curl "https://api.flipbird.io/api/v1/audit/range?from=string&to=string" \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "from": "string",
  "to": "string",
  "total": 1,
  "entries": [
    {
      "id": "string",
      "actorType": "string",
      "actorId": "…",
      "action": "string",
      "targetType": "string",
      "targetId": "…",
      "meta": {},
      "createdAt": 1767225600000
    }
  ],
  "nextCursor": "string"
}

Errors

Besides the errors any endpoint can answer, these endpoints answer:

StatusCodeWhen
400bad_rangeThe range is not valid days, runs backwards, or covers more than 366 days, from and to included.
400bad_cursorThe cursor was not given by this listing.
422too_many_entriesThe range holds more than 50,000 entries. details.total says how many.