Skip to content

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
    Write Create and update resources
    Manage Clients Manage client records
    Manage Webhooks Manage webhook subscriptions
    Full Access Everything above

  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 the key as a bearer token in the Authorization header:

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

Replace <your-api-endpoint> with your workspace's API endpoint.

All v2 endpoints live under /api/v2/ and return a standardized response envelope with data and meta fields.

Rate limits

API key requests are rate-limited to 100 requests per minute per key by default. 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

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

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.