API Reference

API Overview

Comprehensive reference for the Interna REST API. All endpoints, parameters, and response formats documented.

Base URL

All API requests should be made to the following base URL:

https://api.interna.dev/v1

For sandbox/testing, use https://sandbox-api.interna.dev/v1 instead.

Authentication

Authenticate requests by including your API key in the Authorization header:

cURL

curl https://api.interna.dev/v1/users \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json"

Request Format

The API accepts JSON-encoded request bodies and returns JSON-encoded responses.

Headers

Header	Required	Description
`Authorization`	`Yes`	`Bearer token with your API key`
`Content-Type`	`For POST/PUT`	`Must be application/json`
`X-Request-Id`	`No`	`Idempotency key for safe retries`
`X-Api-Version`	`No`	`API version override (default: latest)`

Response Format

All responses follow a consistent envelope format:

Success Response

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-03-15T10:30:00Z"
  }
}

Status Codes

Code	Meaning	Description
`200`	`OK`	`Request succeeded`
`201`	`Created`	`Resource created successfully`
`400`	`Bad Request`	`Invalid request parameters`
`401`	`Unauthorized`	`Missing or invalid API key`
`403`	`Forbidden`	`Insufficient permissions`
`404`	`Not Found`	`Resource does not exist`
`429`	`Too Many Requests`	`Rate limit exceeded`
`500`	`Server Error`	`Internal server error`

Pagination

List endpoints support cursor-based pagination:

Paginated Request

# First page
curl "https://api.interna.dev/v1/users?limit=25"

# Next page
curl "https://api.interna.dev/v1/users?limit=25&cursor=eyJpZCI6InVzcl8yeEs5bVBxUiJ9"

Rate Limits

Rate limit information is included in response headers. See the Rate Limiting guide for details.

Endpoints

Method	Endpoint	Description
`GET`	`/v1/users`	`List all users`
`POST`	`/v1/users`	`Create a new user`
`GET`	`/v1/users/:id`	`Get a user by ID`
`PUT`	`/v1/users/:id`	`Update a user`
`DELETE`	`/v1/users/:id`	`Delete a user`
`GET`	`/v1/organizations`	`List organizations`
`POST`	`/v1/organizations`	`Create an organization`
`GET`	`/v1/auth/token`	`Generate access token`
`POST`	`/v1/auth/revoke`	`Revoke a token`