GEN Agents API
Create, read, update, and delete agents and their avatars.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/gen-pro:gen-pro-agents-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Auto Content Engine Agents API
description: 'The GEN Auto Content Engine API takes a raw idea all the way to a published video — agent setup, idea research, vidsheet production, layer composition, render, and publish.
## The 5-step journey
Every operation belongs to one phase of a 5-step user journey. Each operation carries an `x-phase` extension you can filter on:
| Phase | Meaning |
|-------|---------|
| `setup` | Step 1 — Set Up Your Agent (identity, voice, personality, API keys, workspaces) |
| `ideas` | Step 2 — Generate Content Ideas (trending data, research, refinement, preferences) |
| `convert` | Step 3 — Convert Idea to Vidsheet (clone template or build custom engine) |
| `edit` | Step 4 — Edit & Generate (cells, layers, creation cards, trigger + poll) |
| `export` | Step 5 — Export & Publish (render, download, publish to social) |
Full journey-oriented docs: https://api.gen.pro
## Authentication
All endpoints require authentication via one of:
- **API Key** (recommended): Pass your API key in the `X-API-Key` header. Create keys on the agent''s API page in the GEN dashboard.
- **JWT**: Pass a Bearer JWT in the `Authorization: Bearer ` header.
## Base URLs
```
https://api.gen.pro/v1 — agent setup, vidsheets, generations, renders, publishing
https://agent.gen.pro/v1 — content ideas, research, conversations, chat
https://agent-core.gen.pro/v1 — agent core (brand profile, watchlists, scheduled tasks)
https://python.gen.pro — social publishing integration (connect, schedule, remove posts)
```
Each operation carries its own `servers` entry, so a generated client or a
hand-written call goes to the backend that serves the route.
## Credits
All `/v1/vidsheet/` endpoints require an active GEN credit balance.
If your organization has no usable credits, requests return `422` with error code `usable_gen_credit_required`.
Credits can be funded with x402 by calling `POST /v1/x402_credit_purchase`
with `workspace_id` plus `amount_usd` or `credits`. If `network` is omitted,
GEN returns every configured payment option in `payment_methods` and
`payment_required.accepts`; show the Sui, Solana, and Base options to the
user or calling agent and sign one selected accept entry. Workspace funding
wallets are backend settlement infrastructure; the user-facing payment
choices are the returned payment methods.'
version: 1.0.0
contact:
name: GEN Support
url: https://gen.pro
license:
name: Proprietary
servers:
- url: https://api.gen.pro/v1
description: Auto Content Engine API
- url: https://agent.gen.pro/v1
description: Agent Chat API
- url: https://agent-core.gen.pro/v1
description: Agent Core API (watchlists)
- url: https://python.gen.pro
description: Publishing integration API (social connect and scheduling)
security:
- apiKey: []
- bearerAuth: []
tags:
- name: Agents
description: Create, read, update, and delete agents and their avatars.
paths:
/agents:
post:
operationId: createAgent
x-mcp-tool: gen_agent_action
x-mcp-branch: create_agent
x-phase: setup
summary: Create an agent
description: Creates a new agent in the specified organization.
tags:
- Agents
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
organization_id:
type: string
description: Organization to create the agent in.
agent:
type: object
required:
- name
properties:
name:
type: string
example: My Brand Agent
description:
type: string
time_zone:
type: string
example: America/New_York
eleven_lab_api_key:
type: string
hume_ai_api_key:
type: string
agent_avatars_attributes:
type: array
items:
type: object
responses:
'201':
description: Agent created
content:
application/json:
schema:
type: object
properties:
agent:
$ref: '#/components/schemas/AgentDetail'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
description: Agent creation failed or organization not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/agents/{agent_id}:
get:
operationId: getAgent
x-mcp-tool: gen_discover
x-mcp-branch: agent.detail
x-phase: setup
summary: Get an agent
description: Returns detailed information about a specific agent.
tags:
- Agents
parameters:
- $ref: '#/components/parameters/AgentIdPath'
- name: with_organization_uuid
in: query
schema:
type: boolean
description: Include organization UUID in response.
responses:
'200':
description: Agent details
content:
application/json:
schema:
$ref: '#/components/schemas/AgentDetail'
'403':
description: Permission denied
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Agent not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/ApiUnauthorized'
patch:
operationId: updateAgent
x-mcp-tool: gen_agent_action
x-mcp-branch: connect_agent_elevenlabs
x-phase: setup
summary: Update an agent
description: Updates agent properties including name, description, timezone, API keys, avatars, and default voice.
tags:
- Agents
parameters:
- $ref: '#/components/parameters/AgentIdPath'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
agent:
type: object
properties:
name:
type: string
description:
type: string
time_zone:
type: string
eleven_lab_api_key:
type: string
hume_ai_api_key:
type: string
agent_avatars_attributes:
type: array
items:
type: object
default_user_voice_attributes:
type: object
properties:
source:
type: string
voice_id:
type: string
responses:
'200':
description: Updated agent
content:
application/json:
schema:
type: object
properties:
agent:
$ref: '#/components/schemas/AgentDetail'
'403':
description: Permission denied
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Agent not found or validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/ApiUnauthorized'
delete:
operationId: deleteAgent
x-mcp-tool: gen_agent_action
x-mcp-branch: delete_agent
x-phase: setup
summary: Delete an agent
description: Permanently deletes an agent and all associated data.
tags:
- Agents
parameters:
- $ref: '#/components/parameters/AgentIdPath'
responses:
'200':
description: Agent deleted
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/ApiUnauthorized'
'422':
$ref: '#/components/responses/ApiValidationError'
/agents/{agent_id}/avatars:
get:
operationId: listAgentAvatars
x-mcp-tool: gen_discover
x-mcp-branch: agent.profile_photos
x-phase: setup
summary: List agent profile photos
description: Returns all avatars for the agent. Cursor-based pagination (20 per page). Primary avatar listed first.
tags:
- Agents
parameters:
- $ref: '#/components/parameters/AgentIdPath'
- name: cursor
in: query
schema:
type: string
description: Pagination cursor.
responses:
'200':
description: List of avatars
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Avatar'
'401':
$ref: '#/components/responses/ApiUnauthorized'
'422':
$ref: '#/components/responses/ApiValidationError'
post:
operationId: createAgentAvatar
x-mcp-tool: gen_agent_action
x-mcp-branch: create_agent_avatar
x-phase: setup
summary: Upload agent avatar
description: Upload one or more avatar images (JPEG, PNG, WebP) or link a DeGod avatar.
tags:
- Agents
parameters:
- $ref: '#/components/parameters/AgentIdPath'
requestBody:
required: true
content:
application/json:
schema:
type: object
description: JSON request body.
properties:
agent_avatars_attributes:
type: array
items:
type: object
properties:
id: {}
degod_avatar_id: {}
file: {}
_destroy: {}
responses:
'200':
description: Avatar(s) created
'422':
description: Avatar creation failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/ApiUnauthorized'
/agents/{agent_id}/avatars/{id}:
delete:
operationId: deleteAgentAvatar
x-mcp-tool: gen_agent_action
x-mcp-branch: delete_agent_avatar
x-phase: setup
summary: Delete avatar(s)
description: Delete one or more avatars. Pass multiple IDs separated by underscores (e.g. `7_8_9`).
tags:
- Agents
parameters:
- $ref: '#/components/parameters/AgentIdPath'
- name: id
in: path
required: true
schema:
type: string
description: Avatar ID or multiple IDs separated by underscores.
responses:
'200':
description: Avatar(s) deleted
'401':
$ref: '#/components/responses/ApiUnauthorized'
'422':
$ref: '#/components/responses/ApiValidationError'
/user_shared_agents:
post:
operationId: postUserSharedAgents
x-phase: setup
summary: Create, update, or remove assistants and their profiles — share agent
tags:
- Agents
requestBody:
required: true
content:
application/json:
schema:
type: object
description: JSON request body.
required:
- user_shared_agent
properties:
user_shared_agent:
type: object
properties:
agent_id: {}
username_or_email: {}
role: {}
responses:
'200':
description: Success.
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ApiValidationError'
x-mcp-tool: gen_agent_action
x-mcp-branch: share_agent
/user_shared_agents/{id}:
get:
operationId: getUserSharedAgentsById
x-phase: setup
summary: Create, update, or remove assistants and their profiles — revoke agent share
tags:
- Agents
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
id: {}
name: {}
time_zone: {}
shared_users:
type: array
items:
type: object
properties:
id: {}
name: {}
email: {}
role: {}
shared_agent_id: {}
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/ApiValidationError'
x-mcp-tool: gen_agent_action
x-mcp-branch: revoke_agent_share
put:
operationId: putUserSharedAgentsById
x-phase: setup
summary: Create, update, or remove assistants and their profiles — set agent share role
tags:
- Agents
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
description: JSON request body.
required:
- user_shared_agent
properties:
user_shared_agent:
type: object
properties:
username_or_email: {}
role: {}
responses:
'200':
description: Success.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/ApiValidationError'
x-mcp-tool: gen_agent_action
x-mcp-branch: set_agent_share_role
delete:
operationId: deleteUserSharedAgentsById
x-phase: setup
summary: Create, update, or remove assistants and their profiles — revoke agent share
tags:
- Agents
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Success.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/ApiValidationError'
x-mcp-tool: gen_agent_action
x-mcp-branch: revoke_agent_share
components:
responses:
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Not found
error_code: not_found
ApiUnauthorized:
description: Missing or invalid authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
ApiValidationError:
description: Validation failed or the request could not be processed.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
Unauthorized:
description: Missing or invalid authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Unauthorized
error_code: unauthorized
parameters:
AgentIdPath:
name: agent_id
in: path
required: true
schema:
type: string
schemas:
ApiError:
type: object
required:
- code
properties:
code:
type: string
description: The stable machine-readable failure code.
message:
type: string
description: Human-readable failure detail.
errors:
type: array
description: Field-level validation failures.
items:
type: object
retryable:
type: boolean
description: Whether retrying can succeed without changing the request.
new_change_set_required:
type: boolean
description: Whether the caller must begin a new edit group.
funding_error_kind:
type: string
description: The credit or payment failure category.
Error:
type: object
required:
- error
properties:
error:
type: string
description: Human-readable error message.
error_code:
type: string
description: Machine-readable error code.
AgentDetail:
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
nullable: true
organization_id:
type: string
time_zone:
type: string
nullable: true
primary_avatar_id:
type: string
nullable: true
primary_avatar_url:
type: string
format: uri
nullable: true
agent_setup_project_id:
type: string
nullable: true
role:
type: string
default_user_voice:
type: object
nullable: true
properties:
id:
type: string
name:
type: string
gender:
type: string
language:
type: string
provider:
type: string
url:
type: string
format: uri
Avatar:
type: object
properties:
id:
type: string
is_primary:
type: boolean
url:
type: string
format: uri
thumbnail_url:
type: string
format: uri
nullable: true
degod_avatar_id:
type: string
nullable: true
securitySchemes:
apiKey:
type: apiKey
in: header
name: X-API-Key
description: Personal Access Token (PAT). Create one in Settings > API Keys.
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Bearer JWT issued by the GEN dashboard sign-in.