Standards and Conventions

Vaultody adheres to the OpenAPI 3.0 standard and RESTful design principles. This page documents the conventions you will encounter throughout the API so you can integrate confidently and predictably.

Base URL

All REST API requests are made to:

https://rest.vaultody.com

HTTPS is required for all requests. HTTP is not supported. The maximum URI length is 2000 characters including path and query string.

URI Structure & Naming

Paths use lowercase letters and spinal-case: /vault-accounts/details
Path parameters use camelCase: {vaultId}, {vaultAccountId}, {blockchain}
Query parameters use camelCase: ?startingAfter=...&isHideEmpty=true
Endpoints are grouped by resource category: /vaults/, /supported-assets, /transaction-requests/, /info/

HTTP Methods

Method	Usage
`GET`	Retrieve a resource or list of resources. No request body.
`POST`	Create a new resource or trigger an action.
`PUT`	Update an existing resource.

Request Requirements

All requests must include Content-Type: application/json
All requests must include the four authentication headers (x-api-key, x-api-sign, x-api-timestamp, x-api-passphrase) — see Vaultody API Authentication
POST and PUT request bodies must follow the envelope structure: { "data": { "item": { ...fields } } }
Request bodies must be valid JSON

Request Body Envelope

Every POST and PUT request body must be wrapped in a data.item envelope:

{
  "data": {
    "item": {
      "name": "My Vault Account",
      "color": "#00C7E6",
      "isHiddenInDashboard": false
    }
  }
}

Omitting this wrapper returns a 422 invalid_request_body_structure error.

An optional context string can be included at the top level of any request body or as a query parameter. It is returned unchanged in the response and can be used to correlate responses with requests in batch or async workflows:

{
  "context": "user-onboarding-flow-step-3",
  "data": {
    "item": {}
  }
}

Response Envelope

Every routed response — success or error — follows a consistent envelope:

{
  "apiVersion": "2026-03-20",
  "requestId": "601c1710034ed6d407996b30",
  "context": "user-onboarding-flow-step-3",
  "data": {
    "item": {}
  }
}

Field	Description
`apiVersion`	The version of the API that handled this request
`requestId`	Unique identifier for this specific request, generated by Vaultody. Include it in support tickets
`context`	Echoed back from your request if you provided one
`data`	Contains `item` (single resource) or `items` + pagination fields (list)

List response:

{
  "apiVersion": "2026-03-20",
  "requestId": "601c1710034ed6d407996b30",
  "data": {
    "limit": 50,
    "startingAfter": "5ca21f92cf5431000105d1a7",
    "hasMore": true,
    "items": []
  }
}

Error response:

{
  "apiVersion": "2026-03-20",
  "requestId": "601c1710034ed6d407996b30",
  "error": {
    "code": "resource_not_found",
    "message": "The specified resource has not been found.",
    "details": [
      {
        "attribute": "vaultAccountId",
        "message": "No vault account found with the provided ID"
      }
    ]
  }
}

Authentication failures are the one exception. Authentication runs before a request is matched to an endpoint and a version, so a rejected request carries only requestId and error:

{
  "requestId": "6a71a78fc2b9edd0ad03e76c",
  "error": {
    "code": "missing_authorization_header",
    "message": "An authorization header is missing, please check our Authorization section in our Documentation."
  }
}

Do not treat apiVersion as a required field in your response parser.

Data Types & Field Conventions

Convention	Example
Amounts are strings, not numbers	`"amount": "0.001"` — not `"amount": 0.001`
Booleans are native JSON booleans	`"isHiddenInDashboard": false`
Timestamps are UNIX integers in seconds	`"createdAt": 1760621154`
IDs are hex strings	`"vaultAccountId": "68dfaeae39a4b80007c4f707"`
Colors are hex color codes	`"color": "#00C7E6"`

HTTP Status Codes

Status	Meaning
200 OK	Request succeeded (GET, PUT)
201 Created	Resource successfully created (POST)
400 Bad Request	Malformed request — invalid path parameter, pagination error, or bad blockchain/network value
401 Unauthorized	Authentication failed — missing header, invalid API key, invalid signature, or an expired timestamp
403 Forbidden	Valid credentials but insufficient permissions, plan restriction, or business rule violation
404 Not Found	The requested resource ID does not exist
409 Conflict	Data validation failure, unknown attribute, insufficient balance, state conflict, or an unknown `x-api-version`
415 Unsupported Media Type	`Content-Type` header is missing or not `application/json`
422 Unprocessable Entity	Request body does not follow the `{ "data": { "item": {} } }` envelope structure
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Unexpected server-side error

API Versioning

Vaultody uses date-based versioning. The current version is 2026-03-20.

Every routed response includes the version that handled the request:

{ "apiVersion": "2026-03-20" }

How versioning works

New versions are released when breaking changes are introduced
Each version is identified by its release date (e.g. 2026-03-20)
You can pin your API key to a specific version in the Dashboard under Developers → API Keys, or pin a single request with the x-api-version header
Non-breaking changes (new optional fields, new endpoints) are added to the current version without a version bump

What constitutes a breaking change

Removing or renaming a field
Changing a field's data type
Changing required fields
Changing the meaning of an existing status code or error code

New optional fields, new endpoints, and new error codes are not considered breaking changes.

Was this page helpful?

Yes