Documentation Index
Fetch the complete documentation index at: https://developers.bloobank.com/llms.txt
Use this file to discover all available pages before exploring further.
The BlooBank Transactions Engine API is a REST API over HTTPS. This page documents the transport-level contract — what every endpoint shares, regardless of the resource.
Base URL
https://txengine.bloobank.com/txengine/v1
v1 is the major version of the API contract; breaking changes will be published under a new major version.
Methods
The API uses HTTP methods with their standard REST semantics.
| Method | Use | Safe? | Idempotent? |
|---|
GET | Retrieve a resource or list. | ✅ | ✅ |
POST | Create a resource. | ❌ | ❌ (use idempotencyKey) |
PUT | Update a resource or trigger a state transition (approve, cancel). | ❌ | ✅ |
DELETE | Not used. | — | — |
POST and idempotency. Create operations are not idempotent by default. Always supply an idempotencyKey when the operation has financial side effects — see Idempotency.Content types
All request and response bodies are JSON.
| Header | Value |
|---|
Content-Type (request) | application/json; charset=utf-8 |
Accept (request, optional) | application/json |
Content-Type (response) | application/json; charset=utf-8 |
INVALID_ARGUMENT (HTTP 400).
Authentication
Every request must carry the four Access Protocol headers — failure to include them, or signature verification failure, returns one of the canonical authentication reasons documented in the Error catalog.
| Header | Required | Format |
|---|
X-Access-Key | ✅ | Opaque string. |
X-Access-Timestamp | ✅ | Unix epoch in milliseconds (UTC). |
X-Access-Request-Id | ✅ | Unique per request (UUID v4 recommended). |
X-Access-Signature | ✅ | Base64-encoded ECDSA secp256k1 signature. |
Status codes
The numeric error.code is always coherent with the HTTP status line. Branch on error.status for business logic — see Errors.
| HTTP | Meaning | When |
|---|
200 OK | Success. | Resource retrieved or updated. |
201 Created | Resource created. | Returned by POST on success. |
400 Bad Request | Request contract violation. | Malformed body, invalid headers, validation failure. |
401 Unauthorized | Authentication failure. | Missing headers, signature invalid, clock skew, replay detected. |
403 Forbidden | Authorization denied. | Authenticated, but not permitted on this resource. |
404 Not Found | Resource does not exist. | Or you are not permitted to know it exists. |
409 Conflict | Conflicts with current state. | Uniqueness violation on create. |
422 Unprocessable Entity | Business precondition failed. | E.g., IDEMPOTENCY_KEY_IN_USE_WITH_DIFFERENT_PARAMS. |
500 Internal Server Error | Internal failure. | Sanitized response — see Errors §INTERNAL. |
503 Service Unavailable | Downstream dependency unavailable. | E.g., PROVIDER_UNAVAILABLE. Retry with backoff. |
Branch on error.status, not error.code. Two 400s can mean different things (INVALID_ARGUMENT vs FAILED_PRECONDITION). Two 401s can mean different things (SIGNATURE_INVALID vs TIMESTAMP_SKEW_EXCEEDED). The numeric code is informational; error.status is the contract.
TLS
All traffic is HTTPS. The server enforces TLS 1.2 or higher; HTTP connections are refused. Certificate pinning is not required — the server uses publicly trusted certificates rotated transparently.
Versioning
The major version is part of the URL path (/v1). Within a major version:
- Additive changes (new endpoints, new response fields, new optional request fields) ship without notice.
- Breaking changes (removed fields, renamed fields, changed semantics) trigger a new major version (
/v2) with a deprecation window for the previous one.
Clients should ignore unknown response fields gracefully — assume the server may add fields at any time.
