Docs

Conventions

Base URL and versioning

REST operations live under https://api.filemark.ca/api/v1; the MCP server is https://api.filemark.ca/mcp. Both are HTTPS only.

Changes within v1 are additive. The OpenAPI schema is the published contract; its info.version rises when operations or fields are added, and a CI gate blocks removals and narrowings of published operations, parameters, request bodies, responses, and response headers. Computation targets version their strict schemas separately through payloadSchemaVersion; see Pin a strict contract.

There is no separate test environment. Every request reads your live workspace, and the API is read-only, so no call can change it; the batch and rollover computations read no workspace data at all. Filemark publishes no client libraries; generate one for your language from the OpenAPI schema.

Requests

  • Send the access token as Authorization: Bearer <access-token>.
  • Bodies are JSON with Content-Type: application/json. The token endpoint alone takes application/x-www-form-urlencoded.
  • Path and query parameters are snake_case (client_id, year_end); JSON fields are camelCase (yearEnd).
  • A body may be up to 16 MiB on /api/v1 and /mcp, and up to 256 KiB at the token endpoint. A larger body is rejected with 413 before it reaches the API.

Responses

  • Bodies are JSON. Collection reads return data and pagination; computations return the envelope described under Run computations.
  • Failures return requestId and an error object with code and message; see error codes.
  • IDs are UUID strings.
  • Timestamps are ISO-8601 in UTC, for example 2026-07-14T12:00:00Z. Dates are YYYY-MM-DD.
  • Money in the saved tax-data reads (trial balance, accounts, adjustments) is an exact decimal string, for example "125000.5" or "-4200", never a float; those reads report debits as positive and credits as negative. Computation inputs and results carry money as JSON numbers; see each target's cells in the computation reference.
  • Enumerations are lowercase strings, snake_case except the document kind values, which are kebab-case. Each enum's members are listed inline in the REST reference.
  • null means unknown or not applicable for that record.

Response headers

HeaderSent onMeaning
X-Request-IdEvery /api/v1 responseOpaque request identifier. Quote it when you report a failed request. MCP carries the same identifier in the tool result's _meta["ca.filemark/requestId"] and in the error envelope's requestId.
WWW-Authenticate401, 403Bearer when no credential was presented, Bearer error="invalid_token" when a token was refused, and Bearer error="insufficient_scope", scope="..." when a valid token lacks a scope; the scope parameter lists what the operation requires.
Retry-After429, 503Seconds to wait before retrying.
X-RateLimit-Limit, X-RateLimit-Remaining429The exhausted budget's window size and the requests left in it.

Retries

Every operation is read-only or stateless, so any request can be retried. On 429 and 503, wait the Retry-After seconds first. Retries count against the same request budgets as first attempts.

Filemark | Conventions