Making Requests

The HyperRep API is a ReSTful API. It supports standard HTTP methods in any programming language. The examples below show cURL and Python requests with the correct headers, path parameters, and query parameters.

Base URL

All examples in this documentation use the following base URL.

https://api.hyperrep.ai

Standard request pattern

Most read requests follow the same structure: send an HTTP GET with your API key in the X-API-KEY header.

For endpoints with query parameters, use curl -G and --data-urlencode (or your HTTP client's params argument).

For write requests (for example, creating message drafts), use POST with a JSON body.

Standard request pattern

curl https://api.hyperrep.ai/api/v2/organizations \
  -H "X-API-KEY: your-api-key"

Example response

{
  "data": [
    {
      "organization_id": "gAAAAABexampleOrganizationIdReturnedByApi7mN4qP2xLs9dV5kTr8cY1hJ6uW3",
      "name": "Acme Roofing"
    }
  ]
}

Request with query parameters

curl -G https://api.hyperrep.ai/api/v2/organizations/gAAAAABexampleOrganizationIdReturnedByApi7mN4qP2xLs9dV5kTr8cY1hJ6uW3/conversations \
  -H "X-API-KEY: your-api-key" \
  --data-urlencode "limit=25" \
  --data-urlencode "start_date=2026-04-01T00:00:00Z" \
  --data-urlencode "end_date=2026-04-30T23:59:59Z"

Example response

{
  "data": [
    {
      "conversation_id": "gAAAAABexampleConversationIdReturnedByApi8kP3xLs7dV2mTr5cN9hY1uJ4",
      "start_at": "2026-04-29T14:00:00Z",
      "last_activity_at": "2026-04-29T16:00:00Z",
      "folder": "inbox",
      "is_read": false,
      "contact_id": "gAAAAABexampleContactIdReturnedByApi4pQ8xLm2sV7kRt1cN5hY9uJ3dF6"
    }
  ],
  "pagination": {
    "limit": 25,
    "cursor": null,
    "next_cursor": null,
    "has_more": false
  }
}

POST request with JSON body

curl https://api.hyperrep.ai/api/v2/organizations/gAAAAABexampleOrganizationIdReturnedByApi7mN4qP2xLs9dV5kTr8cY1hJ6uW3/messages-drafts \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "modality": "email",
    "subject": "Following up on your quote",
    "body_html": "<p>Hi Diana, checking in on your quote.</p>",
    "to_email": "[email protected]",
    "autosend_draft": false
  }'

Example response

{
  "draft_id": "gAAAAABexampleDraftIdReturnedByApi6pN8xLm3sV7kRt2cY5hJ9uW1dF4",
  "queued_to_send": false,
  "send_at": null,
  "folder": "drafts"
}

Path parameters

Many HyperRep endpoints are nested. The IDs used in those paths come from earlier API responses.

Example flows:

Name
organization_id
Description
Get this from GET /api/v2/organizations.
Name
contact_id
Description
Get this from GET /api/v2/organizations/{organization_id}/contacts.
Name
company_id
Description
Get this from GET /api/v2/organizations/{organization_id}/companies.
Name
agent_id
Description
Get this from GET /api/v2/organizations/{organization_id}/agents.
Name
conversation_id
Description
Get this from GET /api/v2/organizations/{organization_id}/conversations.
Name
message_id
Description
Get this from GET /api/v2/organizations/{organization_id}/conversations/{conversation_id}/messages.

Query parameters

Use query parameters where the API supports filtering or pagination.

Name
limit
Description
Controls the number of items returned on paginated contacts, companies, agents, conversations, messages, and sales endpoints.
Name
cursor
Description
Requests the next page by reusing the cursor value returned in a previous response.
Name
start_date
Description
Filters conversations, messages, or sales to items on or after a timestamp, or defines the start of an analytics window.
Name
end_date
Description
Filters conversations, messages, or sales to items before a timestamp, or defines the end of an analytics window.

Analytics request

curl -G https://api.hyperrep.ai/api/v2/organizations/gAAAAABexampleOrganizationIdReturnedByApi7mN4qP2xLs9dV5kTr8cY1hJ6uW3/analytics/conversations/response-rate \
  -H "X-API-KEY: your-api-key" \
  --data-urlencode "start_date=2026-04-01T00:00:00Z" \
  --data-urlencode "end_date=2026-04-30T23:59:59Z"

Example response

{
  "numConversationsRespondedTo": 14,
  "numConversationsReceived": 20,
  "responseRate": 0.7
}