Orq.ai Documentation - AI Gateway & LLM Collaboration Platform

cURL

curl --request GET \
  --url https://api.orq.ai/v2/contacts \
  --header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "_id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "external_id": "user_12345",
      "display_name": "Jane Smith",
      "email": "[email protected]",
      "avatar_url": "https://example.com/avatars/jane-smith.jpg",
      "tags": [
        "premium",
        "beta-user"
      ],
      "metadata": {
        "department": "Engineering",
        "role": "Senior Developer"
      },
      "created": "2024-01-15T10:30:00Z",
      "updated": "2024-01-15T10:30:00Z"
    },
    {
      "_id": "contact_01ARZ3NDEKTSV4RRFFQ69G5XY",
      "external_id": "user_67890",
      "display_name": "John Doe",
      "email": "[email protected]",
      "tags": [
        "enterprise"
      ],
      "metadata": {
        "department": "Sales",
        "role": "Account Manager"
      },
      "created": "2024-01-14T09:15:00Z",
      "updated": "2024-01-14T09:15:00Z"
    }
  ],
  "has_more": false
}

GET

contacts

cURL

curl --request GET \
  --url https://api.orq.ai/v2/contacts \
  --header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "_id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "external_id": "user_12345",
      "display_name": "Jane Smith",
      "email": "[email protected]",
      "avatar_url": "https://example.com/avatars/jane-smith.jpg",
      "tags": [
        "premium",
        "beta-user"
      ],
      "metadata": {
        "department": "Engineering",
        "role": "Senior Developer"
      },
      "created": "2024-01-15T10:30:00Z",
      "updated": "2024-01-15T10:30:00Z"
    },
    {
      "_id": "contact_01ARZ3NDEKTSV4RRFFQ69G5XY",
      "external_id": "user_67890",
      "display_name": "John Doe",
      "email": "[email protected]",
      "tags": [
        "enterprise"
      ],
      "metadata": {
        "department": "Sales",
        "role": "Account Manager"
      },
      "created": "2024-01-14T09:15:00Z",
      "updated": "2024-01-14T09:15:00Z"
    }
  ],
  "has_more": false
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

limit

number

default:10

A limit on the number of objects to be returned. Limit can range between 1 and 50, and the default is 10

Required range: 1 <= x <= 50

starting_after

string

A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with 01JJ1HDHN79XAS7A01WB3HYSDB, your subsequent call can include after=01JJ1HDHN79XAS7A01WB3HYSDB in order to fetch the next page of the list.

ending_before

string

A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with 01JJ1HDHN79XAS7A01WB3HYSDB, your subsequent call can include before=01JJ1HDHN79XAS7A01WB3HYSDB in order to fetch the previous page of the list.

string

Search contacts by display name or email address. Minimum 2 characters required.

Example:

"john"

filter_by

object

Filter contacts by tags. Can be provided as JSON object {"tags": ["premium", "beta-user"]} or as query format "tags=premium,beta-user"

Show child attributes

filter_by.tags

string[]

Example:

{ "tags": ["premium", "beta-user"] }

include_metrics

boolean | null

default:false

Include usage metrics of the last 30 days for each contact.

Response

200 - application/json

List of contacts

object

enum<string>

required

Available options:

list

data

object[]

required

Show child attributes

data._id

string<ulid>

required

Unique ULID (Universally Unique Lexicographically Sortable Identifier) for the contact

Example:

"contact_01ARZ3NDEKTSV4RRFFQ69G5FAV"

data.external_id

string

required

Unique string value to identify the contact user in the customer's system. This should be the same ID you use in your system to reference this user.

Required string length: 1 - 120

Example:

"user_12345"

data.metrics

object

required

Show child attributes

data.metrics.total_cost

number

required

Total cost in dollars of the last 30 days

Example:

100

data.metrics.total_tokens

number

required

Total tokens of the last 30 days

Example:

1000

data.metrics.total_requests

number

required

Total requests of the last 30 days

Example:

1000

data.metrics.error_rate

number

required

P50 error rate of the last 30 days

Example:

22

data.display_name

string | null

Display name or nickname of the contact user. This is typically shown in user interfaces.

Example:

"Jane Smith"

data.email

string<email> | null

Email address of the contact user

Example:

"[email protected]"

data.avatar_url

string<uri> | null

URL linking to the contact user's avatar image

Example:

"https://example.com/avatars/jane-smith.jpg"

data.tags

string[]

Array of tags associated with the contact. Useful for organizing and filtering contacts by categories, departments, or custom classifications.

Example:

["premium", "beta-user", "enterprise"]

data.metadata

object

Additional custom metadata associated with the contact as key-value pairs. Use this to store any extra information specific to your application.

Show child attributes

data.metadata.{key}

any

Example:

{
  "department": "Engineering",
  "role": "Senior Developer",
  "subscription_tier": "premium",
  "last_login": "2024-01-15T10:30:00Z"
}

data.created

default:2025-12-08T10:34:25.077Z

The date and time the resource was created

data.updated

default:2025-12-08T10:34:25.079Z

The date and time the resource was last updated

has_more

boolean

required

Parse text

Create a contact

⌘I

Platform APIs

Gateway APIs

List contacts

Authorizations

Query Parameters

Response