Endpoint Reference

Complete reference for all Envizion AI API endpoints. All endpoints require authentication and return JSON. The base URL is https://api.envizion.ai.

On this page

Agents Runs Tools Marketplace Credits Renders Downloads Webhooks Usage API Keys

Agents

Create, list, retrieve, and delete AI agent pipelines.

GET/v1/agentsread

List all agents visible to the authenticated user, including public agents and agents you own.

Query Parameters

`page`	integer	Page number (default: 1)
`limit`	integer	Results per page (default: 20, max: 100)

Example Request

cURL

curl -s https://api.envizion.ai/v1/agents \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "agents": [
    {
      "id": "a1b2c3d4-...",
      "name": "Creative Director",
      "slug": "creative_director",
      "description": "Full video production...",
      "pipeline_type": "graph",
      "tools": ["write_script", "source_assets"],
      "is_public": true,
      "install_count": 42,
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "total": 25,
  "page": 1
}

GET/v1/agents/{agent_id}read

Retrieve a single agent by ID or slug. Returns full configuration including tools, graph edges, and cosmetics.

Path Parameters

agent_id* string Agent UUID or slug (e.g., creative_director)

Example Request

cURL

curl -s https://api.envizion.ai/v1/agents/creative_director \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "id": "a1b2c3d4-...",
  "name": "Creative Director",
  "slug": "creative_director",
  "description": "Full production pipeline",
  "pipeline_type": "graph",
  "tools": ["write_script", "source_assets",
    "generate_voiceover", "render_video"],
  "graph_edges": [
    {"source": "write_script",
     "target": "source_assets"}
  ],
  "requirements": {...},
  "cosmetics": {...},
  "created_at": "2026-01-15T10:30:00Z"
}

POST/v1/agentswrite

Create a new agent with a tool pipeline. Supports simple (linear), sequential, graph, and DAG pipeline types.

Request Body

`name`*	string	Display name for the agent
`tools`*	string[]	List of tool slugs to include
`description`	string	Human-readable description
`pipeline_type`	string	Pipeline type: simple, sequential, graph, dag (default: simple)
`graph_edges`	object[]	Edge definitions for graph/dag pipelines
`requirements`	object	Input requirements specification
`cosmetics`	object	Visual branding configuration

Example Request

cURL

curl -s -X POST https://api.envizion.ai/v1/agents \
  -H "X-API-Key: vk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "News Recap Bot",
    "tools": ["write_script", "source_assets",
              "generate_voiceover", "render_video"],
    "pipeline_type": "sequential",
    "description": "Creates daily news recaps"
  }'

Example Response

JSON

{
  "id": "e5f6g7h8-...",
  "name": "News Recap Bot",
  "slug": "news_recap_bot",
  "description": "Creates daily news recaps",
  "pipeline_type": "sequential",
  "tools": ["write_script", "source_assets",
    "generate_voiceover", "render_video"],
  "is_public": false,
  "created_at": "2026-02-12T15:00:00Z"
}

DELETE/v1/agents/{agent_id}write

Delete an agent you own. System agents and agents owned by other users cannot be deleted.

Path Parameters

agent_id* string Agent UUID

Example Request

cURL

curl -s -X DELETE \
  https://api.envizion.ai/v1/agents/e5f6g7h8-... \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "deleted": true,
  "id": "e5f6g7h8-..."
}

Runs

Execute agents and monitor their progress in real-time.

POST/v1/runswrite

Start a new agent run. The run executes asynchronously. Use the stream endpoint or webhooks to track progress.

Request Body

`agent_id`*	string	Agent UUID or slug
`inputs`	object	Input data for the agent (topic, style, etc.)
`project_id`	string	Existing project UUID to update (optional)

Example Request

cURL

curl -s -X POST https://api.envizion.ai/v1/runs \
  -H "X-API-Key: vk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "creative_director",
    "inputs": {
      "topic": "AI breakthroughs in 2026",
      "style": "documentary",
      "duration": 60
    }
  }'

Example Response

JSON

{
  "id": "run_abc123...",
  "agent_id": "a1b2c3d4-...",
  "status": "pending",
  "result": {},
  "error": null,
  "credits_used": 0,
  "created_at": "2026-02-12T15:30:00Z",
  "completed_at": null
}

GET/v1/runs/{run_id}read

Get the current state of a run, including status, result, error details, and credit usage.

Path Parameters

run_id* string Run UUID

Example Request

cURL

curl -s https://api.envizion.ai/v1/runs/run_abc123 \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "id": "run_abc123...",
  "agent_id": "a1b2c3d4-...",
  "status": "completed",
  "result": {
    "project_id": "proj_xyz789...",
    "summary": "Created 60s documentary...",
    "video_url": "s3://vision/renders/..."
  },
  "error": null,
  "credits_used": 15.0,
  "created_at": "2026-02-12T15:30:00Z",
  "completed_at": "2026-02-12T15:32:45Z"
}

GET/v1/runs/{run_id}/streamreadSSE

Stream real-time Server-Sent Events for a run. Events include tool progress, intermediate results, and the final completion event. The connection stays open until the run completes or fails (up to 10 minutes).

Path Parameters

run_id* string Run UUID

Example Request

cURL

curl -N https://api.envizion.ai/v1/runs/run_abc123/stream \
  -H "X-API-Key: vk_your_key"

Example Events

SSE

data: {"type":"tool_start","tool":"write_script"}

data: {"type":"tool_complete","tool":"write_script",
       "result":{"script":"..."}}

data: {"type":"run_complete","status":"completed",
       "result":{"project_id":"proj_xyz789"}}

data: [DONE]

POST/v1/runs/{run_id}/cancelwrite

Cancel a running agent execution. Only works on runs in pending or running status.

Path Parameters

run_id* string Run UUID

Example Request

cURL

curl -s -X POST \
  https://api.envizion.ai/v1/runs/run_abc123/cancel \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "id": "run_abc123...",
  "status": "cancelled",
  "cancelled_at": "2026-02-12T15:31:00Z"
}

Tools

Browse the catalog of 52 built-in tools available for agent pipelines.

GET/v1/toolsread

List all available tools in the platform catalog, including their input/output schemas and categories.

Example Request

cURL

curl -s https://api.envizion.ai/v1/tools \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "tools": [
    {
      "id": "t1...",
      "slug": "write_script",
      "name": "Script Writer",
      "description": "AI-powered script...",
      "category": "writing",
      "input_schema": {...},
      "output_schema": {...}
    },
    {
      "id": "t2...",
      "slug": "source_assets",
      "name": "Asset Sourcer",
      "category": "media"
    }
  ],
  "total": 52
}

GET/v1/tools/{tool_id}read

Get detailed information about a single tool, including full input/output schemas.

Path Parameters

tool_id* string Tool UUID or slug

Example Request

cURL

curl -s https://api.envizion.ai/v1/tools/write_script \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "id": "t1...",
  "slug": "write_script",
  "name": "Script Writer",
  "description": "AI-powered script generation",
  "category": "writing",
  "input_schema": {
    "topic": {"type": "string", "required": true},
    "style": {"type": "string"},
    "duration": {"type": "integer"}
  },
  "output_schema": {
    "script": {"type": "string"},
    "segments": {"type": "array"}
  }
}

Marketplace

Browse and install pre-built agent templates from the marketplace.

GET/v1/marketplace/templatesread

List all public marketplace templates. Optionally filter by category.

Query Parameters

category string Filter by category (e.g., news, sports, education)

Example Request

cURL

curl -s https://api.envizion.ai/v1/marketplace/templates \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "templates": [
    {
      "id": "tmpl_1...",
      "name": "Sports Highlight Reel",
      "slug": "sports_highlight_reel",
      "description": "Auto-generate sports...",
      "category": "sports",
      "tools": ["write_script", "find_moments",
        "source_assets", "render_video"],
      "install_count": 156,
      "is_public": true
    }
  ]
}

GET/v1/marketplace/templates/{template_id}read

Get full details of a marketplace template, including tools, graph edges, and example outputs.

Path Parameters

template_id* string Template UUID or slug

Example Request

cURL

curl -s https://api.envizion.ai/v1/marketplace/templates/sports_highlight_reel \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "id": "tmpl_1...",
  "name": "Sports Highlight Reel",
  "slug": "sports_highlight_reel",
  "description": "Full description...",
  "category": "sports",
  "tools": ["write_script", "find_moments",
    "source_assets", "render_video"],
  "graph_edges": [...],
  "install_count": 156
}

POST/v1/marketplace/templates/{template_id}/installwrite

Install a marketplace template as a new agent in your account. Creates a personal copy you can customize.

Path Parameters

template_id* string Template UUID or slug

Example Request

cURL

curl -s -X POST \
  https://api.envizion.ai/v1/marketplace/templates/sports_highlight_reel/install \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "id": "a9b8c7d6-...",
  "name": "Sports Highlight Reel",
  "slug": "sports_highlight_reel_copy",
  "description": "Full description...",
  "pipeline_type": "graph",
  "tools": ["write_script", "find_moments",
    "source_assets", "render_video"],
  "is_public": false,
  "created_at": "2026-02-12T16:00:00Z"
}

Credits

Check your credit balance and transaction history.

GET/v1/credits/walletread

Get the current credit balance, plan information, and lifetime usage statistics.

Example Request

cURL

curl -s https://api.envizion.ai/v1/credits/wallet \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "balance": 450.0,
  "plan_name": "starter",
  "lifetime_earned": 1000.0,
  "lifetime_spent": 550.0,
  "monthly_allowance": 500,
  "next_refill_at": "2026-03-01T00:00:00Z"
}

GET/v1/credits/transactionsread

List credit transactions showing debits and credits with timestamps and descriptions.

Query Parameters

`limit`	integer	Results per page (default: 50, max: 100)
`offset`	integer	Number of results to skip (default: 0)

Example Request

cURL

curl -s "https://api.envizion.ai/v1/credits/transactions?limit=10" \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "transactions": [
    {
      "id": "tx_1...",
      "amount": -15.0,
      "type": "debit",
      "description": "Agent run: creative_director",
      "run_id": "run_abc123",
      "created_at": "2026-02-12T15:32:45Z"
    },
    {
      "id": "tx_2...",
      "amount": 500.0,
      "type": "credit",
      "description": "Monthly plan refill",
      "created_at": "2026-02-01T00:00:00Z"
    }
  ]
}

Renders

Trigger video renders and track their progress.

POST/v1/renderswrite

Trigger a video render for a project. Supports resolution, codec, and format options. Renders are queued and processed asynchronously.

Request Body

`project_id`*	string	Project UUID to render
`options`	object	Render options (resolution, codec, format, aspect_ratio)

Example Request

cURL

curl -s -X POST https://api.envizion.ai/v1/renders \
  -H "X-API-Key: vk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_xyz789",
    "options": {
      "resolution": "1080p",
      "codec": "h264",
      "format": "mp4"
    }
  }'

Example Response

JSON

{
  "id": "render_abc...",
  "status": "pending",
  "progress": 0,
  "output_url": null,
  "error": null,
  "created_at": "2026-02-12T16:00:00Z"
}

GET/v1/renders/{render_id}read

Get the current status and progress of a render job. Progress is a float from 0 to 100.

Path Parameters

render_id* string Render job UUID

Example Request

cURL

curl -s https://api.envizion.ai/v1/renders/render_abc \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "id": "render_abc...",
  "status": "completed",
  "progress": 100,
  "output_url": "s3://vision/renders/...",
  "error": null,
  "created_at": "2026-02-12T16:00:00Z",
  "completed_at": "2026-02-12T16:03:22Z"
}

Downloads

Generate presigned download URLs for rendered videos.

GET/v1/downloads/projects/{project_uuid}read

Generate a time-limited presigned URL for downloading a rendered video. Only works for projects you own that have completed rendering.

Path Parameters

project_uuid* string Project UUID

Query Parameters

expires_in integer URL expiry in seconds (1-86400, default: 3600)

Example Request

cURL

curl -s "https://api.envizion.ai/v1/downloads/projects/proj_xyz789?expires_in=7200" \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "download_url": "https://s3.example.com/vision/renders/...?X-Amz-Signature=...",
  "expires_in": 7200,
  "project_uuid": "proj_xyz789",
  "content_type": "video/mp4"
}

Webhooks

Manage webhook endpoints for receiving event notifications. See the Webhook Guide for integration details.

POST/v1/webhookswrite

Request Body

`url`*	string	HTTPS callback URL (10-2048 chars)
`events`*	string[]	Event types to subscribe to

Example Request

cURL

curl -s -X POST https://api.envizion.ai/v1/webhooks \
  -H "X-API-Key: vk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/vision",
    "events": ["run.completed", "render.completed"]
  }'

Example Response

JSON

{
  "url": "https://your-app.com/webhooks/vision",
  "events": ["run.completed", "render.completed"],
  "secret": "whsec_aBcDeFgHiJkLmNoPqRs...",
  "message": "Webhook created. Save the secret -- it won't be shown again."
}

GET/v1/webhooksread

List all webhooks for the authenticated user, including status and failure counts.

Example Request

cURL

curl -s https://api.envizion.ai/v1/webhooks \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "webhooks": [
    {
      "id": "wh_1...",
      "url": "https://your-app.com/webhooks/vision",
      "events": ["run.completed", "render.completed"],
      "is_active": true,
      "failure_count": 0,
      "created_at": "2026-02-10T12:00:00Z"
    }
  ]
}

DELETE/v1/webhooks/{webhook_id}write

Delete a webhook endpoint. Stops all future deliveries.

Path Parameters

webhook_id* string Webhook UUID

Example Request

cURL

curl -s -X DELETE \
  https://api.envizion.ai/v1/webhooks/wh_1 \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "deleted": true
}

POST/v1/webhooks/{webhook_id}/testwrite

Send a test event to verify webhook connectivity. Delivers a test payload with HMAC signature.

Path Parameters

webhook_id* string Webhook UUID

Example Request

cURL

curl -s -X POST \
  https://api.envizion.ai/v1/webhooks/wh_1/test \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "status": "delivered",
  "response_status": 200,
  "response_body": "OK"
}

GET/v1/webhooks/{webhook_id}/deliveriesread

List recent delivery attempts for a webhook, including response codes and retry counts.

Path Parameters

webhook_id* string Webhook UUID

Query Parameters

limit integer Max results (default: 20)

Example Request

cURL

curl -s "https://api.envizion.ai/v1/webhooks/wh_1/deliveries?limit=5" \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "deliveries": [
    {
      "id": "del_1...",
      "webhook_id": "wh_1",
      "event_type": "run.completed",
      "payload": {...},
      "response_status": 200,
      "response_body": "OK",
      "attempt": 1,
      "created_at": "2026-02-12T15:33:00Z"
    }
  ]
}

GET/v1/webhooks/eventsread

List all available webhook event types.

Example Request

cURL

curl -s https://api.envizion.ai/v1/webhooks/events \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "events": [
    "agent.installed",
    "credits.low",
    "publish.completed",
    "publish.failed",
    "render.completed",
    "render.failed",
    "run.completed",
    "run.failed"
  ]
}

Usage

Monitor your API usage with analytics and metrics.

GET/v1/usage/summaryread

Get an aggregated usage summary including total requests, error rates, and latency percentiles.

Query Parameters

days integer Lookback period in days (1-365, default: 30)

Example Request

cURL

curl -s "https://api.envizion.ai/v1/usage/summary?days=7" \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "period_days": 7,
  "total_requests": 1234,
  "active_days": 6,
  "avg_response_time_ms": 245.3,
  "p95_response_time_ms": 890.1,
  "success_count": 1200,
  "error_count": 34,
  "error_rate": 2.76
}

GET/v1/usage/dailyread

Get daily request counts, error counts, and average latency for chart visualization.

Query Parameters

days integer Lookback period in days (1-90, default: 30)

Example Request

cURL

curl -s "https://api.envizion.ai/v1/usage/daily?days=7" \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "data": [
    {
      "date": "2026-02-06",
      "requests": 180,
      "errors": 3,
      "avg_latency_ms": 210.5
    },
    {
      "date": "2026-02-07",
      "requests": 220,
      "errors": 5,
      "avg_latency_ms": 195.2
    }
  ]
}

GET/v1/usage/by-endpointread

Get request counts grouped by endpoint path and HTTP method. Returns the top 20 most-called endpoints.

Query Parameters

days integer Lookback period in days (1-90, default: 30)

Example Request

cURL

curl -s "https://api.envizion.ai/v1/usage/by-endpoint?days=30" \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "endpoints": [
    {
      "path": "/v1/agents",
      "method": "GET",
      "requests": 450,
      "avg_latency_ms": 120.3,
      "errors": 2
    },
    {
      "path": "/v1/runs",
      "method": "POST",
      "requests": 380,
      "avg_latency_ms": 340.1,
      "errors": 8
    }
  ]
}

GET/v1/usage/by-keyread

Get request counts grouped by API key. Useful for identifying which key generates the most traffic.

Query Parameters

days integer Lookback period in days (1-90, default: 30)

Example Request

cURL

curl -s "https://api.envizion.ai/v1/usage/by-key?days=30" \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "keys": [
    {
      "key_name": "Production Key",
      "key_prefix": "vk_aBcDeFgH",
      "requests": 980,
      "avg_latency_ms": 215.7,
      "errors": 12,
      "last_used": "2026-02-12T15:30:00Z"
    }
  ]
}

API Keys

Manage API keys programmatically. These endpoints use the /api-keys prefix (not /v1).

GET/api-keysread

List all API keys for the authenticated user. The full key secret is never returned in list responses.

Example Request

cURL

curl -s https://api.envizion.ai/api-keys \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "keys": [
    {
      "id": "key_1...",
      "name": "Production Key",
      "key_prefix": "vk_aBcDeFgH",
      "scopes": ["read", "write"],
      "rate_limit_tier": "starter",
      "is_active": true,
      "expires_at": "2026-05-13T00:00:00Z",
      "created_at": "2026-02-12T12:00:00Z",
      "last_used_at": "2026-02-12T15:30:00Z"
    }
  ],
  "total": 1
}

POST/api-keyswrite

Create a new API key. Returns the full key secret once. Maximum 10 active keys per user.

Request Body

`name`*	string	Human-readable name for the key
`scopes`*	string[]	List of scopes: read, write, billing, publish, admin
`expires_in_days`	integer	Auto-expire after N days (optional)

Example Request

cURL

curl -s -X POST https://api.envizion.ai/api-keys \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Key",
    "scopes": ["read", "write"],
    "expires_in_days": 30
  }'

Example Response

JSON

{
  "id": "key_2...",
  "name": "CI/CD Key",
  "key": "vk_aBcDeFgHiJkLmNoPqRsTuVwXyZ...",
  "key_prefix": "vk_aBcDeFgH",
  "scopes": ["read", "write"],
  "rate_limit_tier": "starter",
  "is_active": true,
  "expires_at": "2026-03-14T12:00:00Z",
  "created_at": "2026-02-12T12:00:00Z"
}

DELETE/api-keys/{key_id}write

Revoke an API key. The key is immediately deactivated and can no longer be used for authentication.

Path Parameters

key_id* string API key UUID

Example Request

cURL

curl -s -X DELETE \
  https://api.envizion.ai/api-keys/key_1 \
  -H "X-API-Key: vk_your_key"

Example Response

JSON

{
  "revoked": true,
  "key_id": "key_1"
}

POST/api-keys/{key_id}/rotatewrite

Rotate a key: generates a new key with the same name, scopes, and configuration. The old key is immediately revoked.

Path Parameters

key_id* string API key UUID to rotate

Example Request

cURL

curl -s -X POST \
  https://api.envizion.ai/api-keys/key_1/rotate \
  -H "X-API-Key: vk_your_current_key"

Example Response

JSON

{
  "id": "key_3...",
  "name": "Production Key",
  "key": "vk_NewKeySecretHere...",
  "key_prefix": "vk_NewKeyPr",
  "scopes": ["read", "write"],
  "rate_limit_tier": "starter",
  "is_active": true,
  "expires_at": "2026-05-13T00:00:00Z",
  "created_at": "2026-02-12T16:00:00Z"
}

→Webhook Guide →SDK Reference →Error Reference