Getting Started

1. Authentication

The Enprompta API supports two authentication methods: API Keys for server-to-server communication and OAuth2 Client Credentials for applications requiring scoped access.

API Keys (Recommended)

API keys are the simplest way to authenticate. Generate one from your dashboard and include it in the Authorization header.

Request Header

Authorization: Bearer ep_your_api_key_here

Keep your API keys secure

Never expose API keys in client-side code or public repositories.

OAuth2 Client Credentials

For applications requiring scoped access, use the OAuth2 client credentials flow.

Token Request

curl -X POST https://enprompta.com/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "scope": "prompts:read prompts:write"
  }'

Available OAuth2 scopes:

prompts:readprompts:writeexecutions:readexecutions:writeteams:readteams:writewebhooks:manageanalytics:read

2. Your First Request

Let's make a simple request to list your prompts. This verifies your authentication is working correctly.

cURLGET

curl https://enprompta.com/api/v1/prompts \
  -H "Authorization: Bearer ep_your_api_key"

Response

{
  "success": true,
  "data": [
    {
      "id": "prompt_abc123",
      "title": "Email Writer",
      "content": "Write a professional email about {{topic}}",
      "visibility": "PRIVATE",
      "version": 1,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "total_count": 1,
    "limit": 20
  }
}

You're all set!

If you see a successful response, your authentication is configured correctly.

3. Error Handling

All API errors follow a consistent format with numeric error codes for easy handling.

Error Response Format

{
  "success": false,
  "error": {
    "code": 1001,
    "type": "AUTH_INVALID_TOKEN",
    "message": "The provided API key is invalid or expired",
    "request_id": "req_abc123xyz",
    "documentation_url": "https://docs.enprompta.com/errors/1001"
  }
}

Error Code Ranges

Range	Category	Description
`1xxx`	Authentication	Invalid tokens, expired keys, missing credentials
`2xxx`	Validation	Invalid input, schema errors, missing fields
`3xxx`	Resource	Not found, already exists, conflicts
`4xxx`	Rate Limiting	Rate limit exceeded, quota exhausted
`5xxx`	Server	Internal errors, service unavailable

4. Rate Limits

Rate limits are applied per API key and vary by endpoint and subscription tier.

Tier	Requests/min	Requests/day
Pro	60	10,000
Team	300	100,000
Enterprise	1,000	Unlimited

Rate limit headers are included in every response:

X-RateLimit-Limit: 60

X-RateLimit-Remaining: 45

X-RateLimit-Reset: 1705312800

5. Idempotency

For safe retries on POST, PUT, and PATCH requests, include an Idempotency-Key header.

Idempotent Request

curl -X POST https://enprompta.com/api/v1/prompts \
  -H "Authorization: Bearer ep_your_api_key" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Prompt", "content": "Hello {{name}}"}'

Keys must be 1-255 alphanumeric characters (underscores and hyphens allowed)
Duplicate requests with the same key return the cached response
Keys expire after 24 hours
The response includes X-Idempotent-Replayed: true if cached

6. Pagination

List endpoints use cursor-based pagination for efficient traversal of large datasets.

Paginated Request

# First page
curl "https://enprompta.com/api/v1/prompts?limit=20"

# Next page using cursor
curl "https://enprompta.com/api/v1/prompts?limit=20&cursor=eyJpZCI6IjEyMyJ9"

Pagination Response

{
  "success": true,
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6IjEyMyIsInNvcnQiOiIyMDI0LTAxLTE1In0",
    "previous_cursor": null,
    "total_count": 150,
    "limit": 20
  }
}

On this page