API Reference

The ioZen API v1 is available at https://app.iozen.ai/api/v1/.

All endpoints require authentication via Bearer token. Responses follow a consistent envelope format.

Base URL

https://app.iozen.ai/api/v1

Response Format

Success

{
  "success": true,
  "data": { ... }
}

Error

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human-readable description",
    "details": { ... }
  }
}

See the Error Reference for all error codes and troubleshooting.

Common Headers

Request Headers

Header	Required	Description
`Authorization`	Yes	`Bearer iozen_live_your_key_here`
`Content-Type`	For POST/PATCH	`application/json`
`Idempotency-Key`	Optional (POST)	Unique string to prevent duplicate operations

Response Headers

Header	Description
`X-Request-Id`	Unique request identifier for debugging
`X-RateLimit-Limit`	Max requests per window
`X-RateLimit-Remaining`	Requests remaining
`X-RateLimit-Reset`	Window reset time (Unix ms)

Endpoints

Intake Bots

Method	Endpoint	Scope	Description
`GET`	`/intake-bots`	`read:intake-bots`	List all intake bots
`GET`	`/intake-bots/:id`	`read:intake-bots`	Get a single intake bot

Submissions

Method	Endpoint	Scope	Description
`GET`	`/intake-bots/:id/submissions`	`read:submissions`	List submissions for an intake bot
`GET`	`/intake-bots/:id/submissions/:submissionId`	`read:submissions`	Get a single submission
`POST`	`/intake-bots/:id/submissions`	`write:intake-bots`	Create a new submission

Webhooks

Method	Endpoint	Scope	Description
`GET`	`/webhooks`	`manage:webhooks`	List webhook endpoints
`GET`	`/webhooks/:id`	`manage:webhooks`	Get a single webhook endpoint
`POST`	`/webhooks`	`manage:webhooks`	Register a webhook endpoint
`DELETE`	`/webhooks/:id`	`manage:webhooks`	Delete a webhook endpoint

Pagination

List endpoints use cursor-based pagination. See the Pagination guide for details.

curl "https://app.iozen.ai/api/v1/intake-bots?limit=10&cursor=clxyz..." \
  -H "Authorization: Bearer iozen_live_your_key_here"

Parameter	Type	Default	Description
`limit`	integer	50	Max items per page (1–100)
`cursor`	string	—	Cursor from previous response's `next_cursor`

Idempotency

For POST endpoints, you can pass an Idempotency-Key header to safely retry requests without creating duplicate resources:

curl -X POST https://app.iozen.ai/api/v1/intake-bots/BOT_ID/submissions \
  -H "Authorization: Bearer iozen_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -d '{"data": {"name": "Jane Doe"}}'

Idempotency keys are scoped to your API key
Keys expire after 24 hours
Reusing a key with a different request body returns a 409 idempotency_conflict error
Reusing a key with the same request body returns the original response

Request Body Limits

Write endpoints (POST, PATCH, PUT) enforce a maximum request body size of 1 MB. Requests exceeding this limit receive a 400 validation_failed error.

On this page