Conventions

Base URL and versioning

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

The OpenAPI schema defines the published API contract. Changes within v1 can add operations and fields while preserving existing operations, parameters, request and response bodies, and response headers. Its info.version identifies the API version. Computation schemas are versioned separately through payloadSchemaVersion. See Pin a strict contract.

Record requests use your live workspace, and writes change it. Batch and rollover computations use the inputs you send. Export jobs create filing handoff packages or separate scenario draft packages for download in Filemark.

Filemark has no separate test environment or published client libraries. You can generate a client library from the OpenAPI schema.

Requests

  • Send the access token as Authorization: Bearer <access-token>.
  • Bodies are JSON with Content-Type: application/json. Only the token endpoint takes application/x-www-form-urlencoded.
  • Path and query parameters are snake_case (client_id, year_end) and JSON fields are camelCase (yearEnd).
  • Request bodies can be up to 16 MiB on /api/v1 and /mcp, and up to 256 KiB at the token endpoint. Larger bodies return 413.
  • Writes take an Idempotency-Key header, and changes to an existing record take its version in If-Match. See Write data.

Responses

  • JSON collection responses contain data and pagination. Computation responses are 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.
  • Saved trial balances, accounts, and adjustments represent money as decimal strings such as "125000.5" or "-4200", with debits positive and credits negative. Computation inputs and results use JSON numbers. See the computation reference for each cell's type.
  • Enumerations are lowercase snake_case strings, except the document kind values, which are kebab-case. Each enum's members are listed in the REST reference.
  • null means unknown or not applicable for that record.

Response headers

HeaderSent onMeaning
X-Request-IdEvery /api/v1 responseRequest identifier to include in support requests. MCP provides it in _meta["ca.filemark/requestId"] and the error response'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.
ETagResponses for a record you can changeThe record's resourceVersion in quotes. Send it back in If-Match.
Retry-After429, 503, and 409 idempotency_in_progressSeconds to wait before retrying.
X-RateLimit-Limit, X-RateLimit-Remaining429Request limit and remaining allowance for the rate limit that was reached.

Retries

You can retry reads and computations. To retry export creation or any other write, reuse the original Idempotency-Key to get the same result. On 412, read the record again before retrying with its new version. On 429 and 503, wait the number of seconds in Retry-After before retrying. Retries count toward rate limits.

Filemark | Conventions