Skip to content
/
Update work item

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

Knowledge

Manage knowledge sources and documents

Operations

Jobs

Manage scheduled AI jobs

Operations

Work Items

Track billable AI work tasks

Operations

List work items

Request

Returns a list of all billable work items for your organization.

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

Responses

Success

Bodyapplication/json
workItemsArray of objects(WorkItem)
Response
application/json
{
  "workItems": [
    { … }
  ]
}

Create work item

Request

Creates a new billable work item.

Security
ApiKeyAuth and OrgIdAuth
Bodyapplication/jsonrequired
agentIdstring(uuid)

Agent that performed the work

jobIdstring(uuid)

Associated job if applicable

typestringrequired

Type of work performed

Enum"model_call""knowledge_call""skill_call""job_task"
Example: "model_call"
descriptionstring

Work description

timeSpentstringrequired

Time spent in hours (decimal)

Example: "0.25"
humanInLoopboolean

Whether human intervention was required

Default false
metadataobject

Additional metadata

curl -i -X POST \
  https://hyfn.redocly.app/_mock/openapi/work_items \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-org-id: YOUR_API_KEY_HERE' \
  -d '{
    "agentId": "6310db44-39c9-4e4d-8b67-83c45700e545",
    "jobId": "deaf5733-cb4c-40ec-9b59-5de3fab80a80",
    "type": "model_call",
    "description": "Customer support chat",
    "timeSpent": "0.5",
    "metadata": {
      "modelName": "gpt-4",
      "tokensUsed": 1500
    }
  }'

Responses

Created

Bodyapplication/json
workItemobject(WorkItem)
Response
application/json
{
  "workItem": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "orgId": "string",
    "agentId": "bc309ecf-5f66-4057-93c5-6611cc9cb7b2",
    "jobId": "9d222c6d-893e-4e79-8201-3c9ca16a0f39",
    "type": "model_call",
    "description": "Customer support chat",
    "timeSpent": "0.5",
    "humanInLoop": false,
    "metadata": { … },
    "createdAt": "2019-08-24T14:15:22Z"
  }
}

Get work item

Request

Returns details of a specific work item.

Security
ApiKeyAuth and OrgIdAuth
Path
workItemIdstring(uuid)required

Unique identifier for the work item

Example: 5f6bce01-643e-4f68-a976-02f9a9cdba9f
curl -i -X GET \
  https://hyfn.redocly.app/_mock/openapi/work_items/5f6bce01-643e-4f68-a976-02f9a9cdba9f \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-org-id: YOUR_API_KEY_HERE'

Responses

Success

Bodyapplication/json
workItemobject(WorkItem)
Response
application/json
{
  "workItem": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "orgId": "string",
    "agentId": "bc309ecf-5f66-4057-93c5-6611cc9cb7b2",
    "jobId": "9d222c6d-893e-4e79-8201-3c9ca16a0f39",
    "type": "model_call",
    "description": "Customer support chat",
    "timeSpent": "0.5",
    "humanInLoop": false,
    "metadata": { … },
    "createdAt": "2019-08-24T14:15:22Z"
  }
}

Update work item

Request

Updates an existing work item. Note work items are immutable by design for audit purposes.

Security
ApiKeyAuth and OrgIdAuth
Path
workItemIdstring(uuid)required

Unique identifier for the work item

Example: 5f6bce01-643e-4f68-a976-02f9a9cdba9f
Bodyapplication/jsonrequired
descriptionstring
metadataobject
curl -i -X PATCH \
  https://hyfn.redocly.app/_mock/openapi/work_items/5f6bce01-643e-4f68-a976-02f9a9cdba9f \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-org-id: YOUR_API_KEY_HERE' \
  -d '{
    "description": "string",
    "metadata": {}
  }'

Responses

Success

Bodyapplication/json
workItemobject(WorkItem)
Response
application/json
{
  "workItem": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "orgId": "string",
    "agentId": "bc309ecf-5f66-4057-93c5-6611cc9cb7b2",
    "jobId": "9d222c6d-893e-4e79-8201-3c9ca16a0f39",
    "type": "model_call",
    "description": "Customer support chat",
    "timeSpent": "0.5",
    "humanInLoop": false,
    "metadata": { … },
    "createdAt": "2019-08-24T14:15:22Z"
  }
}

Delete work item

Request

Soft-deletes a work item (maintains audit trail).

Security
ApiKeyAuth and OrgIdAuth
Path
workItemIdstring(uuid)required

Unique identifier for the work item

Example: 5f6bce01-643e-4f68-a976-02f9a9cdba9f
curl -i -X DELETE \
  https://hyfn.redocly.app/_mock/openapi/work_items/5f6bce01-643e-4f68-a976-02f9a9cdba9f \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-org-id: YOUR_API_KEY_HERE'

Responses

Success - no content

Response
No content

Invoices

Access invoices and billing information (read-only)

Operations

Skills

Browse and execute integration actions from connected tools

Operations