API Documentation

Everything you need to integrate Agent OTP into your AI agents and automation workflows.

Base URL

https://agent-otp-production-d7d7.up.railway.app

Authentication

Agent OTP uses two authentication methods:

Method	Used For	Header
API Key	Numbers API (rent, wait, release)	`X-API-Key: ak_xxx`
Bearer Token	Account API (usage, quota, settings)	`Authorization: Bearer xxx`

For the Numbers API, include your API key in the X-API-Key header.

Request Header

# Include your API key in all requests
X-API-Key: ak_your_api_key_here

Keep your API key secret

Never share your API key or commit it to version control.

Quick Start

Get your first OTP in 3 simple steps:

1

Rent a phone number

curl -X POST "https://agent-otp-production-d7d7.up.railway.app/api/v1/numbers/rent" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country": "CA"}'

2

Use the number for verification

Submit the phone number to any service that requires SMS verification.

3

Wait for the OTP

curl -X POST "https://agent-otp-production-d7d7.up.railway.app/api/v1/numbers/+14165551234/wait-for-otp" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timeout_seconds": 120}'

Rent a Number

Get a temporary phone number to receive SMS verification codes.

POST /api/v1/numbers/rent

Request Body

Parameter	Type	Description
country	string	Country code (e.g., "CA", "US")
timeout_seconds	integer	Rental duration (default: 300)

Response

{
  "success": true,
  "message": "Number rented successfully",
  "data": {
    "number": "+14165551234",
    "country": "CA",
    "status": "rented",
    "rented_at": "2026-01-27T14:00:00Z",
    "expires_at": "2026-01-27T14:05:00Z",
    "rental_id": "rent_abc123"
  }
}

Wait for OTP

Block until an OTP is received or timeout. No polling needed!

POST /api/v1/numbers/{number}/wait-for-otp

Request Body

Parameter	Type	Description
timeout_seconds	integer	Max wait time (default: 120)
expected_sender	string	Filter by sender (optional)

Response (Success)

{
  "success": true,
  "message": "OTP received",
  "data": {
    "status": "received",
    "code": "847291",
    "raw_message": "Your verification code is 847291",
    "from_number": "+15551234567",
    "received_at": "2026-01-27T14:01:30Z",
    "wait_time_seconds": 15.5
  }
}

Get Messages

Retrieve all SMS messages received on a rented number.

GET /api/v1/numbers/{number}/messages

Response

{
  "success": true,
  "data": [
    {
      "id": "msg_123",
      "from": "+15551234567",
      "to": "+14165551234",
      "body": "Your verification code is 847291",
      "received_at": "2026-01-27T14:01:30Z",
      "otp_code": "847291"
    }
  ]
}

Release Number

Release a rented number early when you're done with it.

DELETE /api/v1/numbers/{number}

Response

{
  "success": true,
  "message": "Number +14165551234 released successfully"
}

Usage & Quota

Check your API usage and remaining quota.

GET /api/v1/auth/usage/quota

Requires Bearer token authentication (not API key)

Response

{
  "plan": "pro",
  "limit": 200,
  "used": 45,
  "remaining": 155,
  "has_quota": true
}

Error Handling

All errors return a consistent JSON structure.

Error Response

{
  "success": false,
  "error": "Error message description"
}

HTTP Status Codes

Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - Quota exceeded
404	Not Found - Resource doesn't exist
500	Server Error