Flexura API Documentation

All API requests require an API key. Include it as a Bearer token in the Authorization header:

Authorization: Bearer fx_live_xxxxxxxxxxxx

Create your API key at /dashboard. Store it in the MEDIA_GATEWAY_API_KEY environment variable.

Install the Flexura skill into any AI agent with a single command. The script auto-detects your agent environment:

curl -fsSL http://localhost:3000/api/install/flexura-skill | bash

Or target a specific agent:

# OpenAI Codex
curl -fsSL http://localhost:3000/api/install/flexura-skill | bash --target codex

# Cursor
curl -fsSL http://localhost:3000/api/install/flexura-skill | bash --target cursor

# Windsurf
curl -fsSL http://localhost:3000/api/install/flexura-skill | bash --target windsurf

# Claude Desktop
curl -fsSL http://localhost:3000/api/install/flexura-skill | bash --target claude

# Aider
curl -fsSL http://localhost:3000/api/install/flexura-skill | bash --target aider

# Cline
curl -fsSL http://localhost:3000/api/install/flexura-skill | bash --target cline

Search the internet with AI-optimized results. Returns a direct answer plus full page content from top results. Synchronous — no polling needed.

Request Body

Examples

curl -X POST http://localhost:3000/api/search \
  -H "Authorization: Bearer $MEDIA_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest AI agent news",
    "include_answer": true,
    "topic": "news",
    "time_range": "day"
  }'

Response

{
  "query": "latest AI agent news",
  "answer": "Today's top AI agent news includes...",
  "results": [
    {
      "title": "OpenAI Launches Agent SDK",
      "url": "https://openai.com/blog/...",
      "content": "Full extracted page text...",
      "score": 0.97
    }
  ],
  "result_count": 5,
  "response_time_ms": 1240,
  "provider": "tavily"
}

Submit an image generation job. Returns a job_id immediately — poll /api/jobs/{job_id} for the result.

Request Body

Examples

curl -X POST http://localhost:3000/api/generate/image \
  -H "Authorization: Bearer $MEDIA_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a futuristic city at night, neon lights, cinematic",
    "model": "nvidia-flux",
    "options": { "width": 1024, "height": 1024 }
  }'

Response (202 Accepted)

{ "job_id": "abc-123", "status": "queued" }

Submit a video generation job. Same async pattern as image generation — returns a job_id, poll for completion.

curl -X POST http://localhost:3000/api/generate/video \
  -H "Authorization: Bearer $MEDIA_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "a cat playing with a ball of yarn" }'

Submit an audio generation job. Same async pattern — returns a job_id, poll for completion.

curl -X POST http://localhost:3000/api/generate/audio \
  -H "Authorization: Bearer $MEDIA_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "calm ambient background music" }'

Check the status of a generation job. Poll every 5 seconds until status is completed or failed.

Possible Statuses

Response (completed)

{
  "job_id": "abc-123",
  "status": "completed",
  "type": "image",
  "asset_url": "http://localhost:3000/api/assets/abc-123.png",
  "prompt": "a futuristic city at night",
  "created_at": "2026-04-01T00:00:00.000Z",
  "updated_at": "2026-04-01T00:00:12.000Z"
}

Response (failed)

{
  "job_id": "abc-123",
  "status": "failed",
  "error": "Model provider returned an error",
  "type": "image"
}

Returns the live model catalog. Agents should always fetch this before choosing a model — never hardcode model IDs.

curl http://localhost:3000/api/agent/models

Response

{
  "platform": "Flexura",
  "capabilities": {
    "search": {
      "endpoint_url": "http://localhost:3000/api/search",
      "method": "POST",
      "description": "Search the internet with AI-optimized results"
    }
  },
  "models": [
    {
      "id": "nvidia-flux",
      "type": "image",
      "endpoint_url": "http://localhost:3000/api/generate/image",
      "description": "Fast image generation for photorealistic prompts",
      "status": "active",
      "input": {
        "prompt": "string",
        "options": { "width": "number", "height": "number" }
      }
    }
  ]
}