The /api/v1/messages endpoint creates and executes a job immediately, waiting for completion. This is best suited for one-time jobs where you want the result returned in the same request.

POST /api/v1/messages

HeaderTypeRequiredDescription
Content-TypestringYesMust be application/json
x-api-keystringYesYour API key for authentication

The request body contains the job parameters for execution:

FieldTypeRequiredDescription
modelstringYesAI model to use. Options: gpt-auto, gpt-5, gpt-5.2, gpt-5-mini. See models for additional details and options.
message_cache_ttlnumberNoCache TTL in seconds (180-3600). Default: 300 seconds
response_formatobjectYesOutput format specification
messagesarrayYesArray of messages for the conversation
timeoutnumberNoMax wait time in seconds (30-120). Default: 90 seconds

Text Format:

json
{
    "format": "text"
}

JSON Format:

json
{
    "format": "json",
    "schema": {
        "type": "object",
        "properties": {
            "field_name": {
                "type": "string",
                "description": "Description of the field"
            }
        },
        "required": ["field_name"],
        "additionalProperties": false
    }
}

  • At least one message with role: "user" is required
  • Maximum token size per request is based on user's plan. See details in the pricing page
  • Valid roles: system, developer, assistant, user

json
{
    "model": "gpt-auto",
    "timeout": 30,
    "response_format": {
        "format": "text"
    },
    "messages": [
        {
            "role": "user",
            "content": "How many planets are in our solar system?"
        }
    ]
}

This example demonstrates a more complex conversation using all four supported roles:

json
{
    "model": "gpt-auto",
    "timeout": 30,
    "response_format": {
        "format": "text"
    },
    "messages": [
        {
            "role": "system",
            "content": "You are an astronomy expert assistant. Provide accurate and engaging information about space."
        },
        {
            "role": "developer",
            "content": "When listing planets, include their order from the sun and one interesting fact about each. Keep responses under 200 words."
        },
        {
            "role": "user",
            "content": "Tell me about the planets in our solar system."
        },
        {
            "role": "assistant",
            "content": "Our solar system has 8 planets. Starting from the sun: Mercury (closest, extreme temperatures), Venus (hottest planet), Earth (our home), Mars (the Red Planet), Jupiter (largest planet with Great Red Spot), Saturn (famous for its rings), Uranus (rotates on its side), and Neptune (windiest planet)."
        },
        {
            "role": "user",
            "content": "Which one is most similar to Earth?"
        }
    ]
}

Status CodeDescription
200Job completed successfully
202Job created but still processing (timeout occurred)
403Forbidden - insufficient permissions (e.g., free tier using GPT-5)
401Unauthorized - invalid API key
400Bad request - invalid parameters
500Internal server error

json
{
    "success": true,
    "message": "Job completed successfully",
    "data": {
        "status": "completed",
        "job_id": "550e8400-e29b-41d4-a716-446655440000",
        "created_at": 1704067200,
        "result": {
            "response_content": "There are 8 planets in our solar system: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune."
        }
    }
}

json
{
    "success": true,
    "message": "Job created but timed out waiting for completion",
    "data": {
        "status": "timeout",
        "job_id": "550e8400-e29b-41d4-a716-446655440000"
    }
}

json
{
    "success": false,
    "message": "Free tier users cannot use GPT-5 model"
}

Different user tiers have specific limitations:

TierModels AvailableBatch Size Limit
user_freegpt-auto, gpt-5-mini2 jobs per request
user_goAll models10 jobs per request
user_proAll models20 jobs per request
user_maxAll models30 jobs per request

  1. Timeout (408): Creates job and returns job ID for polling
  2. Service Unavailable (503): Creates job and returns job ID for polling
  3. Job Not Found (404): Creates new job and returns job ID

typescript
const API_CONFIG = {
    BASE_URL: "https://api.tokenthon.com",
    ENDPOINT: "/api/v1/messages",
    HEADERS: {
        "Content-Type": "application/json",
        "x-api-key": "your-api-key-here",
    },
};
 
async function createJob(question: string) {
    const response = await fetch(`${API_CONFIG.BASE_URL}${API_CONFIG.ENDPOINT}`, {
        method: "POST",
        headers: API_CONFIG.HEADERS,
        body: JSON.stringify({
            model: "gpt-auto",
            timeout: 30,
            response_format: { format: "text" },
            messages: [
                {
                    role: "user",
                    content: question,
                },
            ],
        }),
    });
 
    const result = await response.json();
 
    if (!response.ok) {
        throw new Error(`Error: ${result.message}`);
    }
 
    return result;
}
 
// Usage
createJob("How many planets are in our solar system?")
    .then((result) => console.log(result))
    .catch((error) => console.error(error));

bash
curl -X POST "https://api.tokenthon.com/api/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "model": "gpt-auto",
    "timeout": 30,
    "response_format": {
      "format": "text"
    },
    "messages": [
      {
        "role": "user",
        "content": "How many planets are in our solar system?"
      }
    ]
  }'