API Overview

---

The FileOnion REST API lets you automate document requests, teams, and sharing from your own systems and tools. API access and API keys are available on Professional and Enterprise plans, and keys can only be managed by Owners and Admins.

Create an API key

1. Go to Settings → Integrations. If your plan includes API access, you'll see the API Keys card.
2. Click New API Key.
3. Enter a Name that describes what the key is for (for example, "Zapier Integration").

4. Pick one or more Scopes:

   Scope	Grants
   Read	Read-only access to your API-accessible resources
   Write	Create and update resources (includes read and sharing)
   Manage Clients	Manage client records
   Manage Teams	Manage teams
   Manage Webhooks	Manage webhook subscriptions
   Full Access	All of the scopes above (not administrative or billing access)

5. Choose an Expiration: 30, 90, or 180 days, 1 year, or never expires.

6. Click Create Key.

Copy your key now

The full key is shown only once, right after creation. It cannot be retrieved again — store it in a secrets manager, not in code or a shared document.

Checkpoint

The API Keys table lists your new key with its masked prefix, scopes, status, creation date, last-used date, and expiration.

To disable a key, click Revoke — any integrations using it stop working immediately, and the key is kept for audit purposes. Delete removes it permanently.

Authentication

Every FileOnion API key starts with the prefix fo_live_. Send it as a bearer token in the Authorization header — that is the only header you need. Do not send X-Tenant-ID; the key already identifies your workspace.

Quickstart — your first call

1. Find your API base URL. It's shown in Settings → Integrations, and in the panel displayed right after you create a key. It looks like https://abc123.execute-api.us-east-1.amazonaws.com/prod and ends in a stage segment — copy the whole value. (Replace <your-api-endpoint> below with it.)

2. Call a read endpoint:

   curl -H "Authorization: Bearer fo_live_your_key_here" \
     "https://<your-api-endpoint>/api/v2/requests/"
   

3. You get the standard envelope back. Every /api/v2/ endpoint returns data plus meta:

   {
     "data": [
       { "id": "req_abc123", "title": "Q3 Financials", "status": "pending" }
     ],
     "meta": { "pagination": { "total": 1, "limit": 25, "nextToken": null } }
   }
   

   An empty workspace returns { "data": [], "meta": { ... } } with HTTP 200 — that's success, not an error.

What API keys can access

API keys can call the customer-facing resource endpoints below. Each call is additionally checked against your key's scopes — read scopes permit GET, write scopes permit POST/PUT/DELETE.

Resource family	Paths	Notes
Requests	/api/v2/requests/…	Document requests + workflow actions
Uploads & files	/api/v2/uploads/…, /api/files/…	File metadata + presigned upload/download
Documents	/api/v2/documents/…
Clients	/api/v2/clients/…	Includes client documents & folders
Subtasks	/api/subtasks/…
Comments	/api/v1/comments/…
Templates	/api/v2/templates/…
Teams	/api/v2/teams/…
Shares	/api/v2/shares/…
Webhooks	/api/v2/webhooks/…	Subscription management (scope manage_webhooks)
Members	/api/v2/members/…	Read (GET) only
Community templates	/api/community-templates/…	Browse (GET) only

Not available to API keys (console-only — an Owner or Admin signed into the web app): managing API keys, billing & subscriptions, members & invitations, SSO/SCIM, roles, audit logs, the encrypted vault, and the AI document routes (/api/uploads/{id}/classify, /add_to_ai_collection, /chat_with_ai_uploaded_documents). Calling any of these with a key returns 403 api_key_forbidden_route.

Rate limits

API key requests are rate-limited to approximately 100 requests per minute per key by default, and your plan may apply additional overall limits. Responses to API-key-authenticated requests include these headers so your integration can back off gracefully:

• X-RateLimit-Limit — the request limit for the window
• X-RateLimit-Remaining — requests remaining in the current window
• X-RateLimit-Reset — when the window resets

Errors

Errors return a JSON body with an error code and a human-readable message.

HTTP	error	What it means
401	missing_authorization / auth_failed	No key sent, or the key is invalid, revoked, or expired
403	api_key_forbidden_route	The endpoint isn't available to API keys (console-only)
403	insufficient_permissions	Your key is missing the scope this endpoint needs
402	trial_expired / tenant_suspended	Workspace billing needs attention
429	rate_limit_exceeded	Slow down; honor the X-RateLimit-* / Retry-After headers

Scopes and capability

Each request is checked against your key's scopes: read scopes permit GET; write scopes permit POST/PUT/DELETE. write also grants sharing; the management scopes (manage_clients, manage_teams) include read. * (Full Access) grants everything a key can do. A call missing the required scope returns 403 insufficient_permissions naming the permission it needs.

Endpoints at a glance

Teams

Method	Endpoint	Description
GET	/api/v2/teams/	List all teams
GET	/api/v2/teams/my-teams	List your teams
POST	/api/v2/teams/	Create a team
GET	/api/v2/teams/{id}	Get team details
PUT	/api/v2/teams/{id}	Update a team
DELETE	/api/v2/teams/{id}	Delete a team
GET	/api/v2/teams/{id}/members	List team members
POST	/api/v2/teams/{id}/members	Add a member
DELETE	/api/v2/teams/{id}/members/{userId}	Remove a member

Shares

Method	Endpoint	Description
POST	/api/v2/shares/	Create a share (user, team, or link)
GET	/api/v2/shares/resource/{id}	List shares for a resource
DELETE	/api/v2/shares/{id}	Revoke a share
GET	/api/v2/shares/link/{token}	Resolve a share link
GET	/api/v2/shares/shared-with-me	List resources shared with you

Request assignment and visibility fields

When creating or updating a request, you can include:

{
  "assigneeUserId": "user-uuid-here",
  "assigneeTeamId": "team-uuid-here",
  "visibility": "tenant | team | private | shared"
}

Both assignee fields are optional; if neither is set, the request is unassigned. If visibility is omitted, it defaults to "tenant" (everyone in the organization). See Teams & Sharing for what each visibility level means.

API key management

These endpoints require a signed-in Owner or Admin (a console session) and cannot be called with an API key:

Method	Endpoint	Description
POST	/api/v2/api-keys	Create a key (raw key returned once)
GET	/api/v2/api-keys	List keys (masked prefixes only)
GET	/api/v2/api-keys/{keyId}	Get key details
PUT	/api/v2/api-keys/{keyId}	Update name, scopes, or status
POST	/api/v2/api-keys/{keyId}/revoke	Revoke a key
DELETE	/api/v2/api-keys/{keyId}	Delete a key permanently

Webhooks

FileOnion can call your systems in two ways:

Event webhooks

Subscribe to events via /api/v2/webhooks. Payloads are signed with HMAC-SHA256 in the X-FileOnion-Signature header so you can verify they came from FileOnion.

Workflow webhook actions

Configure outbound webhooks that fire when a request moves between workflow stages — no code required. From Workflows → Actions, a webhook action supports:

• Methods: POST, PUT, or PATCH
• Authentication: none, bearer token, basic auth, an API key in a custom header, or OAuth2 client credentials
• Custom headers and a custom JSON payload, merged with the request data (which you can toggle off)
• Automatic retries on failure, with configurable max retries and delay

Webhook failures never block the stage transition; failed deliveries are logged for review. See Workflows for setup steps.

Automation platforms

On Professional and Enterprise plans, you can connect FileOnion to Zapier, Make, and n8n using an API key. Create a key with the scopes your automation needs and paste it into the platform's FileOnion connection. See Integrations.

AI Document API

FileOnion's AI document endpoints (summaries and classification) have their own full reference: AI Document API Reference.

Related

• Integrations
• Workflows
• Teams & Sharing
• Security Guide