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
All endpoints are prefixed by resource category: /vaults/, /supported-assets, /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 will result in 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 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 in support tickets.
context	Echoed back from your request if you provided one.
data	Contains `item` (single resource) or `items` + pagination fields (list)

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

Error response envelope:

{
  "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"
      }
    ]
  }
}

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 or invalid API key or signature
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, insufficient balance, or state conflict
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 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
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