The /api/v1/jobs/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/jobs/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-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: developer, user, assistant

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

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_message": "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/jobs/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/jobs/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?"
      }
    ]
  }'