Request and Response Schemas

Conduitt documents every REST operation from the same Zod schemas that validate the live API. The interactive reference at https://api.conduitt.io shows the complete contract for all 529 operations. It covers request bodies, path and query parameters, success responses, and field constraints.

What Every Operation Documents

Each operation includes:

• the exact HTTP method and fully mounted path
• a stable operationId for SDK and client generation
• needed and optional path, query, and body fields
• string formats such as uuid, email, date, and date-time
• minimum and maximum lengths, numeric ranges, array limits, and enum values
• nullable fields and server-applied defaults
• every successful status code and its response schema
• authentication, ownership, retry, concurrency, and state-refresh guidance

Request Bodies

Request bodies are JSON unless an endpoint explicitly documents another content type. You must send a field only when it appears in the schema's required list. nullable: true means that you can send the field as null. It does not mean that you can omit the field.

{
  "invoiceId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "1250.00",
  "paymentMethod": "bank_transfer"
}

Send monetary values in the type documented by the endpoint. Many financial request schemas use decimal strings to preserve precision. Line-item quantity and unit-price fields use JSON numbers.

Response Envelopes

Single-resource responses generally use a data envelope:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "active"
  }
}

Offset-paginated collections add meta:

{
  "data": [],
  "meta": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

Cursor-paginated collections return edges, pageInfo, and totalCount. Read Pagination before you switch a list endpoint to pagination=cursor.

Delete and action endpoints can use a result object instead of data. Always follow the endpoint's named response schema. Do not assume that all operations share one envelope.

Generated Examples

Examples show valid types and formats. They are not reusable identifiers or guaranteed defaults. Generate your own idempotency keys. Use the IDs that your organization returns. Read defaults from the schema, and do not copy an example value.

Errors and Partial Results

Validate the success body only after you check the HTTP status. For 4xx and 5xx responses, use the documented error envelope and preserve field-level validation details. Bulk operations can succeed for some records and skip or reject others. Check the counts and the identifier arrays. HTTP 200 is not proof that every selected record changed.

Client Generation

Download the OpenAPI 3.1 document from:

https://api.conduitt.io/openapi

Regenerate client types when the API version changes. Keep runtime response validation on for critical financial and collection workflows. An unexpected deployment or a stale generated client then fails visibly and does not corrupt local state.

Related Pages

• Authentication
• Pagination
• Errors
• Rate Limits