API behavior & guidelines

General patterns the iBinder APIs follow. Read this once before integrating — it explains the conventions used across every endpoint.

HTTP status codes

iBinder uses standard HTTP status codes.

Code	Meaning
200 OK	The request succeeded.
201 Created	A resource was created. The response body contains the new resource.
400 Bad Request	The request was malformed or invalid.
401 Unauthorized	Missing or invalid access token.
403 Forbidden	The caller is authenticated but not permitted to perform the operation.
404 Not Found	The resource does not exist or is not visible to this tenant.
409 Conflict	The request conflicts with the resource's current state.
429 Too Many Requests	Rate limit exceeded. Back off and retry.
500 Internal Server Error	Unexpected error on the server. Safe to retry idempotent requests.

Request and response format

• All bodies are JSON (Content-Type: application/json).
• Dates and timestamps are ISO 8601 / RFC 3339 (2024-01-15T08:30:00Z).
• Identifiers are either GUIDs (documents, versions, folders) or 9-character NanoIds (binders).

Error responses

Errors return a JSON body alongside the status code. The exact shape depends on whether the error was raised by request validation or by the application:

{
  "type":   "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title":  "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "MetadataFilters[0].metadataElementId": [
      "The metadataElementId field is required."
    ]
  },
  "traceId": "00-4b9b9c0e9c4b4a6b8c1d9e3f7a5b6c2d-1a2b3c4d5e6f7a8b-01"
}

A few things worth pattern-matching on:

• status mirrors the HTTP status code.
• errors is present on validation failures (400) and maps the offending field to one or more messages.
• traceId correlates with iBinder's server-side logs — include it when reporting issues to support.

Authentication and authorization failures may return a shorter body (just type, title, and status).

Pagination, filtering, and sorting

See the dedicated Pagination & filtering guide for the full pattern. In short:

• Pagination uses query parameters (pageSize, pageNumber, searchTerm).
• Filtering and sorting use POST bodies to allow complex queries.

API versioning

The current public API is v1, served at the unversioned base URL:

https://api.ibinder.com/api

iBinder strives to maintain backward compatibility. Additive changes (new endpoints, new optional fields) are not considered breaking and may be deployed at any time. If a breaking change becomes necessary, a new URL-versioned base (e.g. https://api.ibinder.com/v2) will be introduced, and the previous version will continue to work for at least 12 months after the new version is released. Affected customers will be notified directly.

Coding defensively

• Treat unknown JSON fields as optional. New optional response fields can appear at any time.
• Don't depend on response field ordering.
• Use operationId-stable code generation if you generate clients.

Rate limiting and throttling

The API uses rate limiting to prevent abuse. Limits are set based on the type of client and the type of request. If you exceed your limit you will receive 429 Too Many Requests.

When this happens:

1. Back off — wait at least a few seconds before retrying.
2. Honour the Retry-After header if present.
3. If you consistently hit limits, contact iBinder to discuss your integration's needs.

Idempotency

GET requests are always safe to retry. POST requests that create resources are not idempotent unless explicitly documented as such (e.g. the upload commit step, which is keyed by uploadId).

Audit logging

iBinder records an audit trail for actions performed by API integrations. This includes all write operations — document uploads, new versions, metadata changes, deletions — as well as authentication events. These actions are attributed to the integration's client and are visible to tenant administrators alongside actions performed by regular users.

Read access is not logged

Read operations performed through the API are not currently written to the per-document read log that tracks user views in the iBinder UI. If your tenant enables an API integration, document reads made by that integration will not appear in that log.

Tenants opting in to an integration should be aware of this when reasoning about who has accessed a document. Write actions remain fully auditable.