Private API

Programmatic access to your Raqi workspace data.

The Private API gives you programmatic access to your workspace data via RESTful endpoints. Use it to build custom integrations, sync data with external tools, or power your own dashboards.

Getting Your API Key

Navigate to Integrations & API and click Connect on the Private API card. A new API key will be generated with the format rq_live_XXXX. This key is shown only once — copy it immediately and store it securely.

Important: Your API key is hashed with SHA-256 before being stored in our database. The raw key is never saved. If you lose it, you'll need to disconnect and reconnect to generate a new one.

Screenshot Needed

One-time API key display dialog with copy button and security warning

ID: private-api-key-dialog • Suggested: 1200×700

Authentication

All API requests require a Bearer token in the Authorization header:

bash

curl -H "Authorization: Bearer rq_live_your_api_key_here" \
  https://api.raqi.io/api/v1/ping

Available Endpoints

All endpoints are scoped to your workspace and return JSON responses:

Method	Endpoint	Description
GET	/v1/ping	Health check — returns your workspace ID
GET	/v1/contacts	List contacts (supports ?search=, ?page=, ?limit=)
GET	/v1/contacts/:id	Get a single contact by ID
POST	/v1/contacts	Create a new contact
GET	/v1/conversations	List conversations (supports ?status=, ?page=, ?limit=)
GET	/v1/conversations/:id/messages	Get messages in a conversation
GET	/v1/agents	List AI agents
GET	/v1/workspace	Workspace info with contact/conversation/agent counts

Rate Limits

The API is rate-limited to 100 requests per minute per IP address. If you exceed this limit, you'll receive a 429 (Too Many Requests) response.

Code Examples

Create a contact via the API:

bash

curl -X POST \
  -H "Authorization: Bearer rq_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Ahmed", "email": "ahmed@example.com", "phone": "+966501234567", "tags": ["website"]}' \
  https://api.raqi.io/api/v1/contacts

Using Claude instead of curl

Want to drive Raqi from Claude.ai by prompt rather than curl scripts? See the [MCP Server](mcp-server) page for the OAuth-based connector flow — same workspace, same scoping, but no API key to manage.

Was this article helpful?

Integrations & API