Skip to content
/
Get agent by ID

Hyfn Public API (1.0.0)

Public REST API for managing your AI workforce programmatically. Create and manage AI agents, knowledge sources, scheduled jobs, track billable work tasks, and access invoices.

⚠️ SECURITY WARNING: This API is currently in development and uses a system-wide API key. Do not use in production without implementing per-organization API keys. See documentation for details.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL

https://hyfn.ai/support

E-mail

support@hyfn.ai

License

MIT

Languages
Servers
Mock server

https://hyfn.redocly.app/_mock/openapi/

Production server

https://your-domain.replit.app/api/public/

Local development server

http://localhost:5000/api/public/

Agents

Manage AI agents

Operations

List all agents

Request

Returns a list of all AI agents for your organization.

Security
ApiKeyAuth and OrgIdAuth
curl -i -X GET \
  https://hyfn.redocly.app/_mock/openapi/agents \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-org-id: YOUR_API_KEY_HERE'

Responses

Success

Bodyapplication/json
agentsArray of objects(Agent)
Response
application/json
{
  "agents": [
    { … }
  ]
}

Create agent

Request

Creates a new AI agent.

Security
ApiKeyAuth and OrgIdAuth
Bodyapplication/jsonrequired
namestringrequired

Name of the AI agent

Example: "Sales Assistant"
modelProviderstringrequired

AI model provider

Enum"openai""watson_llama""watson_granite""snowflake_cortex"
Example: "openai"
modelNamestringrequired

Name of the AI model

Example: "gpt-4"
systemPromptstring

System prompt for the agent

Example: "You are a helpful sales assistant"
providerConfigobject

Provider-specific configuration

Example: {}
curl -i -X POST \
  https://hyfn.redocly.app/_mock/openapi/agents \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-org-id: YOUR_API_KEY_HERE' \
  -d '{
    "name": "Sales Assistant",
    "modelProvider": "openai",
    "modelName": "gpt-4",
    "systemPrompt": "You are a helpful sales assistant"
  }'

Responses

Created

Bodyapplication/json
agentobject(Agent)
Response
application/json
{
  "agent": {
    "id": "d0312fcf-0bd5-40fe-a5da-1fe1af8e5d13",
    "orgId": "demo-org-123",
    "name": "Sales Assistant",
    "modelProvider": "openai",
    "modelName": "gpt-4",
    "systemPrompt": "You are a helpful sales assistant",
    "providerConfig": {},
    "status": "active",
    "tasksCompleted": 0,
    "deletedAt": null,
    "createdAt": "2025-10-19T19:13:40.453Z",
    "updatedAt": "2025-10-19T19:13:40.453Z"
  }
}

Get agent by ID

Request

Returns details of a specific AI agent.

Security
ApiKeyAuth and OrgIdAuth
Path
agentIdstring(uuid)required

Unique identifier for the AI agent

Example: 6310db44-39c9-4e4d-8b67-83c45700e545
curl -i -X GET \
  https://hyfn.redocly.app/_mock/openapi/agents/6310db44-39c9-4e4d-8b67-83c45700e545 \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-org-id: YOUR_API_KEY_HERE'

Responses

Success

Bodyapplication/json
agentobject(Agent)
Response
application/json
{
  "agent": {
    "id": "6310db44-39c9-4e4d-8b67-83c45700e545",
    "orgId": "demo-org-123",
    "name": "Marketing Bot",
    "modelProvider": "openai",
    "modelName": "gpt-4",
    "systemPrompt": "You are a helpful marketing assistant",
    "providerConfig": {},
    "status": "active",
    "tasksCompleted": 0,
    "deletedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}

Update agent

Request

Updates an existing AI agent.

Security
ApiKeyAuth and OrgIdAuth
Path
agentIdstring(uuid)required

Unique identifier for the AI agent

Example: 6310db44-39c9-4e4d-8b67-83c45700e545
Bodyapplication/jsonrequired
namestring

Name of the AI agent

modelProviderstring

AI model provider

Enum"openai""watson_llama""watson_granite"
modelNamestring

Name of the AI model

systemPromptstring

System prompt for the agent

providerConfigobject

Provider-specific configuration

statusstring

Agent status

Enum"active""inactive"
curl -i -X PATCH \
  https://hyfn.redocly.app/_mock/openapi/agents/6310db44-39c9-4e4d-8b67-83c45700e545 \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-org-id: YOUR_API_KEY_HERE' \
  -d '{
    "name": "Updated Sales Assistant",
    "systemPrompt": "You are an expert sales assistant"
  }'

Responses

Success

Bodyapplication/json
agentobject(Agent)
Response
application/json
{
  "agent": {
    "id": "6310db44-39c9-4e4d-8b67-83c45700e545",
    "orgId": "demo-org-123",
    "name": "Marketing Bot",
    "modelProvider": "openai",
    "modelName": "gpt-4",
    "systemPrompt": "You are a helpful marketing assistant",
    "providerConfig": {},
    "status": "active",
    "tasksCompleted": 0,
    "deletedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}

Delete agent

Request

Deletes an AI agent.

Security
ApiKeyAuth and OrgIdAuth
Path
agentIdstring(uuid)required

Unique identifier for the AI agent

Example: 6310db44-39c9-4e4d-8b67-83c45700e545
curl -i -X DELETE \
  https://hyfn.redocly.app/_mock/openapi/agents/6310db44-39c9-4e4d-8b67-83c45700e545 \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-org-id: YOUR_API_KEY_HERE'

Responses

Success - no content

Response
No content

Knowledge

Manage knowledge sources and documents

Operations

Jobs

Manage scheduled AI jobs

Operations

Work Items

Track billable AI work tasks

Operations

Invoices

Access invoices and billing information (read-only)

Operations

Skills

Browse and execute integration actions from connected tools

Operations