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
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
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)
| Name | Type | Description |
|---|---|---|
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:
| Status | Code | When |
|---|---|---|
| 400 | bad_range | The range is not valid days, runs backwards, or covers more than 366 days, from and to included. |
| 400 | bad_cursor | The cursor was not given by this listing. |
| 422 | too_many_entries | The range holds more than 50,000 entries. details.total says how many. |