Create agent session

import requests

url = "https://app.ubik-agent.com/api/v1/agent-sessions"

payload = {
    "title": "Q3 Analysis",
    "assistant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "model_name": "gpt-4o",
    "initial_system_prompt": "<string>",
    "tool_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "skill_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "external_user_id": "<string>",
    "prompt_variables": {},
    "mcp_config": {}
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    title: 'Q3 Analysis',
    assistant_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    model_name: 'gpt-4o',
    initial_system_prompt: '<string>',
    tool_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    skill_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    external_user_id: '<string>',
    prompt_variables: {},
    mcp_config: {}
  })
};

fetch('https://app.ubik-agent.com/api/v1/agent-sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://app.ubik-agent.com/api/v1/agent-sessions \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "title": "Q3 Analysis",
  "assistant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "model_name": "gpt-4o",
  "initial_system_prompt": "<string>",
  "tool_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "skill_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "external_user_id": "<string>",
  "prompt_variables": {},
  "mcp_config": {}
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "title": "<string>",
  "model_name": "<string>",
  "external_user_id": "<string>",
  "active_tools": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "description": "<string>"
    }
  ],
  "active_skills": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "description": "<string>"
    }
  ],
  "documents": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "status": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "file_type": "<string>",
      "processing_pipeline": "<string>",
      "error_message": "<string>",
      "api_metadata": {},
      "is_starred": false
    }
  ],
  "workspaces": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "document_count": 123,
      "description": "<string>",
      "is_default": false,
      "workspace_metadata": {}
    }
  ],
  "mcp_config": {}
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

POST

agent-sessions

Create agent session

import requests

url = "https://app.ubik-agent.com/api/v1/agent-sessions"

payload = {
    "title": "Q3 Analysis",
    "assistant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "model_name": "gpt-4o",
    "initial_system_prompt": "<string>",
    "tool_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "skill_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "external_user_id": "<string>",
    "prompt_variables": {},
    "mcp_config": {}
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    title: 'Q3 Analysis',
    assistant_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    model_name: 'gpt-4o',
    initial_system_prompt: '<string>',
    tool_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    skill_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    external_user_id: '<string>',
    prompt_variables: {},
    mcp_config: {}
  })
};

fetch('https://app.ubik-agent.com/api/v1/agent-sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://app.ubik-agent.com/api/v1/agent-sessions \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "title": "Q3 Analysis",
  "assistant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "model_name": "gpt-4o",
  "initial_system_prompt": "<string>",
  "tool_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "skill_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "external_user_id": "<string>",
  "prompt_variables": {},
  "mcp_config": {}
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "title": "<string>",
  "model_name": "<string>",
  "external_user_id": "<string>",
  "active_tools": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "description": "<string>"
    }
  ],
  "active_skills": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "description": "<string>"
    }
  ],
  "documents": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "status": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "file_type": "<string>",
      "processing_pipeline": "<string>",
      "error_message": "<string>",
      "api_metadata": {},
      "is_starred": false
    }
  ],
  "workspaces": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "document_count": 123,
      "description": "<string>",
      "is_default": false,
      "workspace_metadata": {}
    }
  ],
  "mcp_config": {}
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Authorizations

X-API-KEY

string

header

required

Headers

X-End-User-ID

string | null

Body

application/json

title

string | null

Optional title for the session.

Example:

"Q3 Analysis"

assistant_id

string<uuid> | null

ID of an assistant to base the session on.

model_name

string | null

Model to use (overrides assistant default).

Example:

"gpt-4o"

initial_system_prompt

string | null

System prompt to initialize the session with.

tool_ids

string<uuid>[] | null

List of tool IDs to enable for this session.

skill_ids

string<uuid>[] | null

List of skill IDs to enable for this session.

external_user_id

string | null

A unique identifier for your end-user. If provided, access to this session will be restricted to requests providing the 'X-End-User-ID' header with this value.

prompt_variables

Prompt Variables · object | null

A dictionary of variables to inject into the system prompt template (e.g. {'tone': 'formal'} for {{tone}}). These variables can be defined in the assistant's parameters (as defaults) or provided here at runtime to override them.

mcp_config

Mcp Config · object | null

Optional MCP configuration to override the assistant's default servers for this session.

Response

Successful Response

string<uuid>

required

Unique identifier for the session.

status

string

required

Current status (e.g., 'active', 'completed').

created_at

string<date-time>

required

Creation timestamp.

updated_at

string<date-time>

required

Last update timestamp.

title

string | null

Title of the session.

model_name

string | null

Model being used.

external_user_id

string | null

The external user ID associated with this session, if any.

active_tools

PublicToolListItem · object[]

List of tools enabled for this session.

Hide child attributes

active_tools.id

string<uuid>

required

The unique identifier for the tool.

active_tools.name

string

required

The name of the tool.

active_tools.description

string | null

A brief description of what the tool does.

active_skills

PublicSkillListItem · object[]

List of skills enabled for this session.

Hide child attributes

active_skills.id

string<uuid>

required

The unique identifier for the skill.

active_skills.name

string

required

The name of the skill.

active_skills.description

string | null

A brief description of what the skill does.

documents

PublicSessionDocumentListItem · object[]

List of documents linked to this session.

Hide child attributes

documents.id

string<uuid>

required

The unique identifier for the document.

documents.name

string

required

The display name of the document.

documents.status

string

required

The current processing status of the document.

documents.created_at

string<date-time>

required

The timestamp when the document was created.

documents.updated_at

string<date-time>

required

The timestamp when the document was last updated.

documents.file_type

string | null

The MIME type of the document file.

documents.processing_pipeline

string | null

The name of the processing pipeline used for this document.

documents.error_message

string | null

If processing failed, this field will contain the error message.

documents.api_metadata

Api Metadata · object | null

Custom API metadata resolved for the current user. Useful for retrieving stored external references (e.g. {'internal_app_ref': 'REF-123'}). Note: This value is resolved based on the request's external_user_id. A document shared globally but also scoped to a specific user may return different metadata depending on who is asking.

documents.is_starred

boolean

default:false

Whether the document is starred in the current session context.

workspaces

PublicWorkspace · object[]

List of workspaces linked to this session.

Hide child attributes

workspaces.id

string<uuid>

required

The unique identifier for the workspace.

workspaces.name

string

required

The name of the workspace.

workspaces.created_at

string<date-time>

required

The timestamp when the workspace was created.

workspaces.updated_at

string<date-time>

required

The timestamp when the workspace was last updated.

workspaces.document_count

integer

required

The number of documents contained within the workspace.

workspaces.description

string | null

A brief description of the workspace's purpose.

workspaces.is_default

boolean | null

default:false

Indicates if this is the default workspace for the user.

workspaces.workspace_metadata

Workspace Metadata · object | null

Metadata for the workspace.

mcp_config

Mcp Config · object | null

The currently active MCP configuration for this session.