API Reference

Complete technical specification for all endpoints.

Base URL

https://app.beginswithai.com/v1

All requests use this prefix.

---

Authentication

All endpoints require authentication via API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Generate API keys at beginswithai.com/api-keys.html in your dashboard.

---

Endpoints

POST /v1/ai

Submit an AI request to the queue.

Request:

POST /v1/ai
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
    "model": "gpt-5.1",
    "prompt": "Your prompt here"
}

Parameters:

Parameter	Type	Required	Description
model	string	Yes	Model identifier (see Models)
prompt	string	Yes	Your input text (cannot be empty)

Response (202 Accepted):

{
    "request_id": "abc123-def456-ghi789",
    "model": "gpt-5.1"
}

Response Fields:

Field	Type	Description
request_id	string	Unique identifier for this request
model	string	The model you requested

Use this request_id to poll for results.

---

GET /v1/ai

Poll for the status and result of a queued request.

Request:

GET /v1/ai?req_id=abc123-def456-ghi789
Authorization: Bearer YOUR_API_KEY

Parameters:

Parameter	Type	Required	Description
req_id	string	Yes	The request_id from your POST request

Response (while processing - 200 OK):

{
    "req_id": "abc123-def456-ghi789",
    "status": "queued"
}

Response (when complete - 200 OK):

{
    "req_id": "abc123-def456-ghi789",
    "model": "gpt-5.1",
    "status": "completed",
    "response": "Async APIs queue requests and return results later, allowing efficient batch processing."
}

Response Fields:

Field	Type	Description
req_id	string	Your request identifier
status	string	Current status (queued or completed)
model	string	The model used
response	string	The AI-generated text (only when status is completed)

---

Request Flow

1. POST /v1/ai
   ↓
2. Receive request_id (202 Accepted)
   ↓
3. Poll GET /v1/ai?req_id=...
   ↓
4. Check status field
   ├─ If "queued": wait 5 seconds, go to step 3
   └─ If "completed": retrieve response field

---

Error Responses

All error responses include a standard format:

{
    "error": "error_code",
    "message": "Human-readable error description"
}

Common Errors:

Status	Error Code	Message	Solution
400	invalid_request	Invalid model, empty prompt, or malformed JSON	Check model name exists; ensure prompt is not empty
401	unauthorized	Missing or invalid API key	Verify Authorization header is set correctly
404	not_found	Request ID doesn't exist or has expired	Check req_id is correct; requests expire after 24 hours
429	rate_limited	Rate limit exceeded for your plan	Wait before retrying; upgrade plan for higher limits
500	server_error	Server-side processing error	Retry after 30 seconds; contact support if persists

See Error Handling for detailed error scenarios and recovery strategies.

Complete Example

Python

import requests
import time

API_KEY = "your_api_key_here"
BASE_URL = "https://app.beginswithai.com/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Submit request
payload = {
    "model": "gpt-5.1",
    "prompt": "Explain async APIs in one sentence"
}

response = requests.post(f"{BASE_URL}/ai", json=payload, headers=headers)
data = response.json()
request_id = data["request_id"]

print(f"Request queued: {request_id}")

# Poll for result
while True:
    poll_response = requests.get(
        f"{BASE_URL}/ai",
        params={"req_id": request_id},
        headers=headers
    )
    result = poll_response.json()

    if "response" in result:
        print(f"\nResult: {result['response']}")
        break

    print("Still processing...")
    time.sleep(5)

JavaScript

const API_KEY = "your_api_key_here";
const BASE_URL = "https://app.beginswithai.com/v1";

const headers = {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
};

async function main() {
    // Submit request
    const payload = {
        model: "gpt-5.1",
        prompt: "Explain async APIs in one sentence"
    };

    const response = await fetch(`${BASE_URL}/ai`, {
        method: "POST",
        headers: headers,
        body: JSON.stringify(payload)
    });

    const data = await response.json();
    const requestId = data.request_id;

    console.log(`Request queued: ${requestId}`);

    // Poll for result
    while (true) {
        const pollResponse = await fetch(
            `${BASE_URL}/ai?req_id=${requestId}`,
            { headers: headers }
        );
        const result = await pollResponse.json();

        if (result.response) {
            console.log(`\nResult: ${result.response}`);
            break;
        }

        console.log("Still processing...");
        await new Promise(resolve => setTimeout(resolve, 5000));
    }
}

main();