Skip to main content

Hyperforge (v1)

API reference for Hyperforge retrieval agent endpoints.

Audit

Audit log and download request endpoints.

Delete Download Request

Delete a download request by its ID

path Parameters
agent_id
required
string (Agent Id)
request_id
required
string (Request Id)

Responses

Response samples

Content type
application/json
null

Get Download Request Status

Get status of an audit download request by its ID

path Parameters
agent_id
required
string (Agent Id)
request_id
required
string (Request Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "string",
  • "status": "pending",
  • "download_url": "string",
  • "query": { }
}

List Download Requests

List all download requests for the account

path Parameters
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Request Interactions Audit Download

Request a download for the audit log of an agent's interactions

path Parameters
agent_id
required
string (Agent Id)
header Parameters
accept
string (Accept)
Default: text/csv
Enum: "application/x-ndjson" "text/csv"
Request Body schema: application/json
required
Session Id (string) or Session Id (null) (Session Id)

Filter by session ID

Year (integer) or Year (null) (Year)

Filter by year (e.g., 2024). If not specified, defaults to the current year.

Month (integer) or Month (null) (Month)

Filter by month (1-12). If not specified, defaults to the past month.

Responses

Request samples

Content type
application/json
{
  • "session_id": "string",
  • "year": 0,
  • "month": 0
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "string",
  • "status": "pending",
  • "download_url": "string",
  • "query": { }
}

Drivers

Driver configuration endpoints.

Patch Driver

Set Agent Configuration

path Parameters
agent_id
required
string (Agent Id)
driver
required
string (Driver)
Request Body schema: application/json
required
Id (string) or Id (null) (Id)
identifier
required
string (Identifier)
name
required
string (Name)
provider
required
any (Provider)

The type of source, e.g., 'google', 'marklogic', etc.

config
required
object (EncryptedPayload)

The configuration specific to the source.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "identifier": "string",
  • "name": "string",
  • "provider": null,
  • "config": { }
}

Response samples

Content type
application/json
null

Delete Driver

Set Agent Configuration

path Parameters
agent_id
required
string (Agent Id)
driver
required
string (Driver)

Responses

Response samples

Content type
application/json
null

Add Driver

Set Agent Configuration

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
Id (string) or Id (null) (Id)
identifier
required
string (Identifier)
name
required
string (Name)
provider
required
any (Provider)

The type of source, e.g., 'google', 'marklogic', etc.

config
required
object (EncryptedPayload)

The configuration specific to the source.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "identifier": "string",
  • "name": "string",
  • "provider": null,
  • "config": { }
}

Response samples

Content type
application/json
{
  • "id": "string"
}

Get Drivers

Get Agent Configuration

path Parameters
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
[
  • { }
]

Import Export

Retrieval Agent import and export endpoints.

Request Export Retrieval Agent

Request the export of a Retrieval Agent. This will send an email with a download link to the email associated with the account.

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
passphrase
required
string (Passphrase) >= 16 characters

Passphrase to encrypt the exported configuration. Will be required for import.

Responses

Request samples

Content type
application/json
{
  • "passphrase": "stringstringstri"
}

Response samples

Content type
application/json
null

Import Retrieval Agent

Import Retrieval Agent Configuration

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: multipart/form-data
required
file
required
string <application/octet-stream> (File)
passphrase
required
string (Passphrase)

Passphrase for the encrypted export file

overwrite
boolean (Overwrite)
Default: false

Whether to overwrite existing agent configuration. If false and the agent configuration is not empty, the import will fail.

Responses

Response samples

Content type
application/json
null

MCP

Model Context Protocol interaction endpoints.

Mcp Handler Delete

path Parameters
agent_id
required
string (Agent Id)
session
required
string (Session)

Responses

Response samples

Content type
application/json
null

Interaction Mcp Handler

path Parameters
agent_id
required
string (Agent Id)
session
required
string (Session)

Responses

Response samples

Content type
application/json
null

Interaction Mcp Handler

path Parameters
agent_id
required
string (Agent Id)
session
required
string (Session)

Responses

Response samples

Content type
application/json
null

Prompt Management

Prompt configuration endpoints.

Patch Prompt

Update Prompt of Agent

path Parameters
agent_id
required
string (Agent Id)
prompt_id
required
string (Prompt Id)
Request Body schema: application/json
required
name
required
string (Name)
description
required
string (Description)
prompt
required
string (Prompt)
Array of Arguments (objects) or Arguments (null) (Arguments)
Icons (object) or Icons (null) (Icons)
Meta (object) or Meta (null) (Meta)
Prompt Id (string) or Prompt Id (null) (Prompt Id)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "prompt": "string",
  • "arguments": [
    ],
  • "icons": {
    },
  • "meta": {
    },
  • "prompt_id": "string"
}

Response samples

Content type
application/json
null

Delete Prompt

Delete prompt id

path Parameters
agent_id
required
string (Agent Id)
prompt_id
required
string (Prompt Id)

Responses

Response samples

Content type
application/json
null

Get Prompt

Get Agent Configuration

path Parameters
agent_id
required
string (Agent Id)
prompt_id
required
string (Prompt Id)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "prompt": "string",
  • "arguments": [
    ],
  • "icons": {
    },
  • "meta": {
    },
  • "prompt_id": "string"
}

Add Prompt

Add Prompt to Agent

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
name
required
string (Name)
description
required
string (Description)
prompt
required
string (Prompt)
Array of Arguments (objects) or Arguments (null) (Arguments)
Icons (object) or Icons (null) (Icons)
Meta (object) or Meta (null) (Meta)
Prompt Id (string) or Prompt Id (null) (Prompt Id)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "prompt": "string",
  • "arguments": [
    ],
  • "icons": {
    },
  • "meta": {
    },
  • "prompt_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string"
}

Get Prompts

Get Agent Configuration

path Parameters
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Sessions

Session management endpoints.

Interaction

Interact session

path Parameters
agent_id
required
string (Agent Id)
session
required
string (Session)
query Parameters
workflow_id
string (Workflow Id)
Default: "default"
Request Body schema: application/json
required
question
required
string (Question)
object (Headers)
Default: {}
object (Arguments)
Default: {}
Array of Chat History (objects) or Chat History (null) (Chat History)

Client-managed chat history. When set (even to an empty list), overrides any server-side session history for agents that use previous Q&A context (rephrase, summarize, smart, etc.). Omit the field entirely to use server-side session history.

operation
integer (InteractionOperation)
Default: 0
Enum: 0 1
streaming
boolean (Streaming)
Default: false

Responses

Request samples

Content type
application/json
{
  • "question": "string",
  • "headers": { },
  • "arguments": { },
  • "chat_history": [
    ],
  • "operation": 0,
  • "streaming": false
}

Response samples

Content type
application/json
null

Patch Session

Create session

path Parameters
agent_id
required
string (Agent Id)
session
required
string (Session)
Request Body schema: application/json
required
slug
required
string (Slug)
name
required
string (Name)
summary
required
string (Summary)
data
required
string (Data)
format
required
string (TextFormat)
Enum: "PLAIN" "HTML" "RST" "MARKDOWN" "JSON" "KEEP_MARKDOWN" "JSONL" "PLAIN_BLANKLINE_SPLIT"

Responses

Request samples

Content type
application/json
{
  • "slug": "string",
  • "name": "string",
  • "summary": "string",
  • "data": "string",
  • "format": "PLAIN"
}

Response samples

Content type
application/json
null

Delete Session

Delete session

path Parameters
agent_id
required
string (Agent Id)
session
required
string (Session)

Responses

Response samples

Content type
application/json
null

Get Session

Create session

path Parameters
agent_id
required
string (Agent Id)
session
required
string (Session)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "slug": "string",
  • "title": "string",
  • "summary": "string",
  • "icon": "string",
  • "thumbnail": "string",
  • "metadata": {
    },
  • "usermetadata": {
    },
  • "fieldmetadata": [
    ],
  • "computedmetadata": {
    },
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "last_seqid": 0,
  • "last_account_seq": 0,
  • "queue": "private",
  • "hidden": true,
  • "origin": {
    },
  • "extra": {
    },
  • "relations": [
    ],
  • "data": {
    },
  • "security": {
    }
}

Create Session

Create session

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
slug
required
string (Slug)
name
required
string (Name)
summary
required
string (Summary)
data
required
string (Data)
format
required
string (TextFormat)
Enum: "PLAIN" "HTML" "RST" "MARKDOWN" "JSON" "KEEP_MARKDOWN" "JSONL" "PLAIN_BLANKLINE_SPLIT"

Responses

Request samples

Content type
application/json
{
  • "slug": "string",
  • "name": "string",
  • "summary": "string",
  • "data": "string",
  • "format": "PLAIN"
}

Response samples

Content type
application/json
{
  • "uuid": "string",
  • "elapsed": 0,
  • "seqid": 0
}

Get Sessions

Create session

path Parameters
agent_id
required
string (Agent Id)
query Parameters
page
integer (Page)
Default: 0

Requested page number (0-based)

size
integer (Size)
Default: 20

Page size

Responses

Response samples

Content type
application/json
{
  • "resources": [
    ],
  • "pagination": {
    }
}

Interaction

Interact session

path Parameters
agent_id
required
string (Agent Id)
session
required
string (Session)
workflow_id
required
string (Workflow Id)
Request Body schema: application/json
required
question
required
string (Question)
object (Headers)
Default: {}
object (Arguments)
Default: {}
Array of Chat History (objects) or Chat History (null) (Chat History)

Client-managed chat history. When set (even to an empty list), overrides any server-side session history for agents that use previous Q&A context (rephrase, summarize, smart, etc.). Omit the field entirely to use server-side session history.

operation
integer (InteractionOperation)
Default: 0
Enum: 0 1
streaming
boolean (Streaming)
Default: false

Responses

Request samples

Content type
application/json
{
  • "question": "string",
  • "headers": { },
  • "arguments": { },
  • "chat_history": [
    ],
  • "operation": 0,
  • "streaming": false
}

Response samples

Content type
application/json
null

Workflow Agents

Workflow Agent configuration and interaction endpoints.

Add Generation

Add Generation Agent Configuration

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
object (BaseModel)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": "string"
}

Get Generation

Set Agent Configuration

path Parameters
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
[
  • null
]

Patch Generation

Set PreProcess Agent Configuration

path Parameters
agent_id
required
string (Agent Id)
generation
required
string (Generation)
Request Body schema: application/json
required
object (BaseModel)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
null

Delete Generation

Delete Generation Agent Configuration

path Parameters
agent_id
required
string (Agent Id)
generation
required
string (Generation)

Responses

Response samples

Content type
application/json
null

Add Postprocess

Add PostProcess Agent Configuration

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
object (BaseModel)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": "string"
}

Get Postprocess

Set Agent Configuration

path Parameters
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
[
  • null
]

Patch Postprocess

Set PostProcess Agent Configuration

path Parameters
agent_id
required
string (Agent Id)
postprocess
required
string (Postprocess)
Request Body schema: application/json
required
object (BaseModel)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
null

Delete Postprocess

Delete PreProcess Agent Configuration

path Parameters
agent_id
required
string (Agent Id)
postprocess
required
string (Postprocess)

Responses

Response samples

Content type
application/json
null

Add Preprocess

Add PreProcess Agent Configuration

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
object (BaseModel)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": "string"
}

Get Preprocess

Set Agent Configuration

path Parameters
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
[
  • null
]

Patch Preprocess

Set PreProcess Agent Configuration

path Parameters
agent_id
required
string (Agent Id)
preprocess
required
string (Preprocess)
Request Body schema: application/json
required
object (BaseModel)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
null

Delete Preprocess

Delete PreProcess Agent Configuration

path Parameters
agent_id
required
string (Agent Id)
preprocess
required
string (Preprocess)

Responses

Response samples

Content type
application/json
null

Add Generation

Add Generation Workflows Configuration

path Parameters
agent_id
required
string (Agent Id)
workflow_id
required
string (Workflow Id)
Request Body schema: application/json
required
object (BaseModel)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": "string"
}

Get Generation

Get Generation Workflows Configuration

path Parameters
agent_id
required
string (Agent Id)
workflow_id
required
string (Workflow Id)

Responses

Response samples

Content type
application/json
[
  • null
]

Patch Generation

Set Generation Workflows Configuration

path Parameters
agent_id
required
string (Agent Id)
workflow_id
required
string (Workflow Id)
generation
required
string (Generation)
Request Body schema: application/json
required
object (BaseModel)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
null

Delete Generation

Delete Generation Workflows Configuration

path Parameters
agent_id
required
string (Agent Id)
workflow_id
required
string (Workflow Id)
generation
required
string (Generation)

Responses

Response samples

Content type
application/json
null

Add Postprocess

Add PostProcess Workflows Configuration

path Parameters
agent_id
required
string (Agent Id)
workflow_id
required
string (Workflow Id)
Request Body schema: application/json
required
object (BaseModel)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": "string"
}

Get Postprocess

Get PostProcess Workflows Configuration

path Parameters
agent_id
required
string (Agent Id)
workflow_id
required
string (Workflow Id)

Responses

Response samples

Content type
application/json
[
  • null
]

Patch Postprocess

Set PostProcess Workflows Configuration

path Parameters
agent_id
required
string (Agent Id)
workflow_id
required
string (Workflow Id)
postprocess
required
string (Postprocess)
Request Body schema: application/json
required
object (BaseModel)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
null

Delete Postprocess

Delete PostProcess Workflows Configuration

path Parameters
agent_id
required
string (Agent Id)
workflow_id
required
string (Workflow Id)
postprocess
required
string (Postprocess)

Responses

Response samples

Content type
application/json
null

Add Preprocess

Add PreProcess Workflows Configuration

path Parameters
agent_id
required
string (Agent Id)
workflow_id
required
string (Workflow Id)
Request Body schema: application/json
required
object (BaseModel)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": "string"
}

Get Preprocess

Set Workflow Configuration

path Parameters
agent_id
required
string (Agent Id)
workflow_id
required
string (Workflow Id)

Responses

Response samples

Content type
application/json
[
  • null
]

Patch Preprocess

Set PreProcess Workflows Configuration

path Parameters
agent_id
required
string (Agent Id)
workflow_id
required
string (Workflow Id)
preprocess
required
string (Preprocess)
Request Body schema: application/json
required
object (BaseModel)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
null

Delete Preprocess

Delete PreProcess Workflows Configuration

path Parameters
agent_id
required
string (Agent Id)
preprocess
required
string (Preprocess)
workflow_id
required
string (Workflow Id)

Responses

Response samples

Content type
application/json
null

Workflows

Workflow configuration endpoints.

Set Rules

Set Agent Configuration

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
Array of Rule (object) or strings (Rules)

List of rules that the workflow should follow. Each rule can be a string or a Rule object with a prompt.

Array
Any of
Prompt (string) or Prompt (null) (Prompt)
Any of
string (Prompt)

Responses

Request samples

Content type
application/json
{
  • "rules": [
    ]
}

Response samples

Content type
application/json
null

Get Rules

Set Agent Configuration

path Parameters
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
null

Set Workflow

Set Workflow Configuration

path Parameters
agent_id
required
string (Agent Id)
workflow_id
required
string (Workflow Id)
Request Body schema: application/json
required
name
required
string (Name)
description
required
string (Description)
required
object (Parameters)
required
Array of strings (Required)
Rules (object) or null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "parameters": { },
  • "required": [
    ],
  • "rules": {
    }
}

Response samples

Content type
application/json
null

Delete Workflow

Delete Workflow Configuration

path Parameters
agent_id
required
string (Agent Id)
workflow_id
required
string (Workflow Id)

Responses

Response samples

Content type
application/json
null

Set Rules

Set Workflow Rules Configuration

path Parameters
agent_id
required
string (Agent Id)
workflow_id
required
string (Workflow Id)
Request Body schema: application/json
required
Array of Rule (object) or strings (Rules)

List of rules that the workflow should follow. Each rule can be a string or a Rule object with a prompt.

Array
Any of
Prompt (string) or Prompt (null) (Prompt)
Any of
string (Prompt)

Responses

Request samples

Content type
application/json
{
  • "rules": [
    ]
}

Response samples

Content type
application/json
null

Get Rules

Get Workflow Rules Configuration

path Parameters
agent_id
required
string (Agent Id)
workflow_id
required
string (Workflow Id)

Responses

Response samples

Content type
application/json
null

Add Workflow

Add Workflow Configuration

path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
id
required
string (Id)
name
required
string (Name)
Description (string) or Description (null) (Description)
Parameters (object) or Parameters (null) (Parameters)
object (Rules)
required
Array of strings (Required)

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "parameters": { },
  • "rules": {
    },
  • "required": [
    ]
}

Response samples

Content type
application/json
null

Get Workflows

Get Workflow Configuration

path Parameters
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]