API Reference

The Fusial API is a REST API for managing your workspace: contracts and their document versions, counterparties and contacts, obligations, templates, and team members. All responses are JSON, and every endpoint is authenticated with a workspace API key.

Base URL

https://app.fusial.com/api/v1

Every path in this reference is relative to that base URL.

Authentication

Authenticate by sending your API key in the x-api-key header:

curl https://app.fusial.com/api/v1/me \
  -H "x-api-key: $FUSIAL_API_KEY"

Create and manage keys in your workspace settings. Each key belongs to a single workspace and is minted as one of two presets:

• Full access — read and write on every resource (templates and analytics remain read-only, as they have no write endpoints).
• Read-only — read on every resource.

Use GET /me to confirm which workspace and scopes a key carries.

Scopes

Keys carry scopes of the form resource:action. Each endpoint lists the scope it requires; a key without it receives 403 insufficient_scope.

Note: attaching or detaching a contract's counterparty is governed by counterparties:write, not contracts:write.

Errors

Errors return a consistent JSON envelope with a stable code, a human-readable message, and optional details:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not have the \"contracts:write\" scope.",
    "details": null
  }
}

Validation failures use 422 validation_error and include the offending fields:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request input.",
    "details": {
      "issues": [{ "path": "title", "message": "String must contain at least 1 character(s)" }]
    }
  }
}

Common status codes:

Pagination

Larger collections — contracts and obligations — are paginated and return a { data, page, pageSize, total, pageCount } envelope. Page through results with ?page=N (1-based):

{
  "data": [],
  "page": 1,
  "pageSize": 50,
  "total": 124,
  "pageCount": 3
}

Smaller collections (contacts, members, versions, templates, and a contract's own obligations) return a bare { "data": [ ... ] } with no page metadata.

Conventions

• Timestamps are ISO 8601 strings (or null).
• Money — a contract's valueCents is in minor units and encoded as a string to preserve precision, with a separate ISO 4217 valueCurrency.
• Single resources are returned under a named key ({ "contract": { ... } }), while collections use { "data": [ ... ] }.

Quickstart

List your most recently active contracts:

curl "https://app.fusial.com/api/v1/contracts?sort=lastActivityAt&dir=desc" \
  -H "x-api-key: $FUSIAL_API_KEY"

Create a contract:

curl -X POST https://app.fusial.com/api/v1/contracts \
  -H "x-api-key: $FUSIAL_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "title": "Acme MSA",
    "type": "MSA",
    "ourRole": "VENDOR",
    "ownerId": "usr_123"
  }'

Browse the endpoints in the sidebar, or jump to a resource below.