openapi: 3.0.3 info: title: Julep Agents API description: Julep AI agents API allows creating agents with long-term memory easily. termsOfService: '' contact: email: [email protected] name: Julep Developers url: https://julep.ai license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html version: 1.0.0 externalDocs: description: Find out more about spec url: https://docs.julep.ai servers: - url: https://api-alpha.julep.ai/api description: '' variables: {} tags: - name: Default description: '' externalDocs: url: https://docs.julep.ai description: https://docs.julep.ai paths: /api/sessions: post: summary: Create a new session description: Create a session between an agent and a user operationId: CreateSession tags: [] parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateSessionRequest' description: Session options description: Session initialization options responses: '201': content: application/json: schema: $ref: '#/components/schemas/ResourceCreatedResponse' description: Session successfully created security: - api-key: [] get: summary: List sessions description: >- List sessions created (use limit/offset pagination to get large number of sessions; sorted by descending order of `created_at` by default) operationId: ListSessions tags: [] parameters: - in: query name: limit description: Number of sessions to return schema: type: integer default: 100 minimum: 1 maximum: 1000 - in: query name: offset description: Number of sessions to skip (sorted created_at descending order) schema: type: integer default: 0 minimum: 0 - in: query name: metadata_filter description: JSON object that should be used to filter objects by metadata required: false schema: type: string default: '{}' - in: query name: sort_by description: 'Which field to sort by: `created_at` or `updated_at`' schema: type: string enum: - created_at - updated_at default: created_at - in: query name: order description: >- Which order should the sort be: `asc` (ascending) or `desc` (descending) schema: type: string enum: - asc - desc default: desc responses: '200': content: application/json: schema: $schema: http://json-schema.org/draft-04/schema# type: object properties: items: type: array items: $ref: '#/components/schemas/Session' required: - items description: >- List of sessions (sorted created_at descending order) with limit+offset pagination security: - api-key: [] /api/users: post: summary: Create a new user description: Create a new user operationId: CreateUser tags: [] parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateUserRequest' description: User create options responses: '201': content: application/json: schema: $ref: '#/components/schemas/ResourceCreatedResponse' description: User successfully created security: - api-key: [] get: summary: List users description: >- List users created (use limit/offset pagination to get large number of sessions; sorted by descending order of `created_at` by default) operationId: ListUsers tags: [] parameters: - in: query name: limit description: Number of items to return schema: type: integer default: 100 minimum: 1 maximum: 1000 - in: query name: offset description: Number of items to skip (sorted created_at descending order) schema: type: integer - in: query name: metadata_filter description: JSON object that should be used to filter objects by metadata required: false schema: type: string default: '{}' - in: query name: sort_by description: 'Which field to sort by: `created_at` or `updated_at`' schema: type: string enum: - created_at - updated_at default: created_at - in: query name: order description: >- Which order should the sort be: `asc` (ascending) or `desc` (descending) schema: type: string enum: - asc - desc default: desc responses: '200': content: application/json: schema: $schema: http://json-schema.org/draft-04/schema# type: object properties: items: type: array items: $ref: '#/components/schemas/User' required: - items description: >- List of users (sorted created_at descending order) with limit+offset pagination security: - api-key: [] /api/agents: post: summary: Create a new agent description: Create a new agent operationId: CreateAgent tags: [] parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAgentRequest' description: Agent create options responses: '201': content: application/json: schema: $ref: '#/components/schemas/ResourceCreatedResponse' description: Agent successfully created security: - api-key: [] get: summary: List agents description: >- List agents created (use limit/offset pagination to get large number of sessions; sorted by descending order of `created_at` by default) operationId: ListAgents tags: [] parameters: - in: query name: limit description: Number of items to return schema: type: integer default: 100 minimum: 1 maximum: 1000 - in: query name: offset description: Number of items to skip (sorted created_at descending order) schema: type: integer default: 0 minimum: 0 - in: query name: metadata_filter description: JSON object that should be used to filter objects by metadata required: false schema: type: string default: '{}' - in: query name: sort_by description: 'Which field to sort by: `created_at` or `updated_at`' schema: type: string enum: - created_at - updated_at default: created_at - in: query name: order description: >- Which order should the sort be: `asc` (ascending) or `desc` (descending) schema: type: string enum: - asc - desc default: desc responses: '200': description: >- List of agents (sorted created_at descending order) with limit+offset pagination content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/Agent' required: - items security: - api-key: [] /api/sessions/{session_id}: get: summary: Get details of the session description: '' operationId: GetSession tags: [] parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/Session' security: - api-key: [] delete: summary: Delete session description: '' operationId: DeleteSession tags: [] parameters: [] responses: '202': content: application/json: schema: $ref: '#/components/schemas/ResourceDeletedResponse' security: - api-key: [] put: summary: Update session parameters description: '' operationId: UpdateSession tags: [] parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateSessionRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/ResourceUpdatedResponse' security: - api-key: [] parameters: - in: path name: session_id description: '' schema: type: string format: uuid required: true patch: summary: Patch Session parameters (merge instead of replace) description: '' operationId: PatchSession tags: [] parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchSessionRequest' responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/ResourceUpdatedResponse' security: - api-key: [] /api/sessions/{session_id}/suggestions: get: summary: Get autogenerated suggestions for session user and agent description: Sorted (created_at descending) operationId: GetSuggestions tags: [] parameters: - in: query name: limit description: '' schema: type: integer default: 100 minimum: 1 maximum: 1000 - in: query name: offset description: '' schema: type: integer default: 0 minimum: 0 responses: '200': content: application/json: schema: $schema: http://json-schema.org/draft-04/schema# type: object properties: items: type: array items: $ref: '#/components/schemas/Suggestion' security: - api-key: [] parameters: - in: path name: session_id description: '' schema: type: string format: uuid required: true /api/sessions/{session_id}/history: get: summary: Get all messages in a session description: Sorted (created_at ascending) operationId: GetHistory tags: [] parameters: - in: query name: limit description: '' schema: type: integer default: 100 minimum: 1 maximum: 1000 - in: query name: offset description: '' schema: type: integer default: 0 minimum: 0 responses: '200': content: application/json: schema: $schema: http://json-schema.org/draft-04/schema# type: object properties: items: type: array items: $ref: '#/components/schemas/ChatMLMessage' security: - api-key: [] parameters: - in: path name: session_id description: '' schema: type: string format: uuid required: true delete: summary: Delete session history (does NOT delete related memories) description: '' operationId: DeleteSessionHistory tags: [] parameters: [] responses: '202': content: application/json: schema: $ref: '#/components/schemas/ResourceDeletedResponse' security: - api-key: [] /api/sessions/{session_id}/chat: parameters: - in: path name: session_id description: '' schema: type: string format: uuid required: true post: summary: Interact with the session description: '' operationId: Chat tags: [] parameters: - in: header name: Accept description: '' schema: type: string default: application/json enum: - application/json - text/event-stream requestBody: content: application/json: schema: $ref: '#/components/schemas/ChatInput' responses: '200': content: application/json: schema: $ref: '#/components/schemas/ChatResponse' security: - api-key: [] /api/agents/{agent_id}/memories: get: summary: Get memories of the agent description: Sorted (created_at descending) operationId: GetAgentMemories tags: [] parameters: - in: query name: query description: '' schema: type: string required: true - in: query name: user_id description: '' schema: type: string format: uuid - in: query name: limit description: '' schema: type: integer - in: query name: offset description: '' schema: type: integer responses: '200': content: application/json: schema: $schema: http://json-schema.org/draft-04/schema# type: object properties: items: type: array items: $ref: '#/components/schemas/Memory' security: - api-key: [] parameters: - in: path name: agent_id description: '' schema: type: string format: uuid required: true /api/users/{user_id}: get: summary: Get details of the user description: '' operationId: GetUser tags: [] parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/User' security: - api-key: [] delete: summary: Delete user description: '' operationId: DeleteUser tags: [] parameters: [] responses: '202': content: application/json: schema: $ref: '#/components/schemas/ResourceDeletedResponse' security: - api-key: [] put: summary: Update user parameters description: '' operationId: UpdateUser tags: [] parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateUserRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/ResourceUpdatedResponse' security: - api-key: [] parameters: - in: path name: user_id description: '' schema: type: string format: uuid required: true patch: summary: Patch User parameters (merge instead of replace) description: '' operationId: PatchUser tags: [] parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchUserRequest' responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/ResourceUpdatedResponse' security: - api-key: [] /api/agents/{agent_id}: get: summary: Get details of the agent description: '' operationId: GetAgent tags: [] parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/Agent' security: - api-key: [] delete: summary: Delete agent description: '' operationId: DeleteAgent tags: [] parameters: [] responses: '202': content: application/json: schema: $ref: '#/components/schemas/ResourceDeletedResponse' security: - api-key: [] put: summary: Update agent parameters description: '' operationId: UpdateAgent tags: [] parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateAgentRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/ResourceUpdatedResponse' security: - api-key: [] parameters: - in: path name: agent_id description: '' schema: type: string format: uuid required: true patch: summary: Patch Agent parameters (merge instead of replace) description: '' operationId: PatchAgent tags: [] parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchAgentRequest' responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/ResourceUpdatedResponse' security: - api-key: [] /api/agents/{agent_id}/docs: get: summary: Get docs of the agent description: Sorted (created_at descending) operationId: GetAgentDocs tags: [] parameters: - in: query name: limit description: '' schema: type: integer - in: query name: offset description: '' schema: type: integer - in: query name: metadata_filter description: JSON object that should be used to filter objects by metadata required: false schema: type: string default: '{}' - in: query name: sort_by description: 'Which field to sort by: `created_at` or `updated_at`' schema: type: string enum: - created_at - updated_at default: created_at - in: query name: order description: >- Which order should the sort be: `asc` (ascending) or `desc` (descending) schema: type: string enum: - asc - desc default: desc requestBody: content: {} responses: '200': content: application/json: schema: $schema: http://json-schema.org/draft-04/schema# type: object properties: items: type: array items: $ref: '#/components/schemas/Doc' security: - api-key: [] parameters: - in: path name: agent_id description: '' schema: type: string format: uuid required: true post: summary: Create doc of the agent description: '' operationId: CreateAgentDoc tags: [] parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateDoc' responses: '201': content: application/json: schema: $ref: '#/components/schemas/ResourceCreatedResponse' security: - api-key: [] /api/users/{user_id}/docs: get: summary: Get docs of the user description: Sorted (created_at descending) operationId: GetUserDocs tags: [] parameters: - in: query name: limit description: '' schema: type: integer - in: query name: offset description: '' schema: type: integer - in: query name: metadata_filter description: JSON object that should be used to filter objects by metadata required: false schema: type: string default: '{}' - in: query name: sort_by description: 'Which field to sort by: `created_at` or `updated_at`' schema: type: string enum: - created_at - updated_at default: created_at - in: query name: order description: >- Which order should the sort be: `asc` (ascending) or `desc` (descending) schema: type: string enum: - asc - desc default: desc requestBody: content: {} responses: '200': content: application/json: schema: $schema: http://json-schema.org/draft-04/schema# type: object properties: items: type: array items: $ref: '#/components/schemas/Doc' security: - api-key: [] parameters: - in: path name: user_id description: '' schema: type: string format: uuid required: true post: summary: Create doc of the user description: '' operationId: CreateUserDoc tags: [] parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateDoc' responses: '201': content: application/json: schema: $ref: '#/components/schemas/ResourceCreatedResponse' security: - api-key: [] /api/users/{user_id}/docs/{doc_id}: parameters: - in: path name: user_id description: '' schema: type: string format: uuid required: true - in: path name: doc_id description: '' schema: type: string format: uuid required: true delete: summary: Delete doc by id description: '' operationId: DeleteUserDoc tags: [] parameters: [] responses: '202': content: application/json: schema: $ref: '#/components/schemas/ResourceDeletedResponse' security: - api-key: [] /api/agents/{agent_id}/docs/{doc_id}: parameters: - in: path name: agent_id description: '' schema: type: string format: uuid required: true - in: path name: doc_id description: '' schema: type: string format: uuid required: true delete: summary: Delete doc by id description: '' operationId: DeleteAgentDoc tags: [] parameters: [] responses: '202': content: application/json: schema: $ref: '#/components/schemas/ResourceDeletedResponse' security: - api-key: [] /api/agents/{agent_id}/memories/{memory_id}: delete: summary: Delete memory of the agent by id description: '' operationId: DeleteAgentMemory tags: [] parameters: [] responses: '202': content: application/json: schema: $ref: '#/components/schemas/ResourceDeletedResponse' security: - api-key: [] parameters: - in: path name: agent_id description: '' schema: type: string format: uuid required: true - in: path name: memory_id description: '' schema: type: string format: uuid required: true /api/agents/{agent_id}/tools: get: summary: Get tools of the agent description: Sorted (created_at descending) operationId: GetAgentTools tags: [] parameters: - in: query name: limit description: '' schema: type: integer - in: query name: offset description: '' schema: type: integer requestBody: content: {} responses: '200': content: application/json: schema: $schema: http://json-schema.org/draft-04/schema# type: object properties: items: type: array items: $ref: '#/components/schemas/Tool' security: - api-key: [] parameters: - in: path name: agent_id description: '' schema: type: string format: uuid required: true post: summary: Create tool for the agent description: '' operationId: CreateAgentTool tags: [] parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateToolRequest' responses: '201': content: application/json: schema: $ref: '#/components/schemas/ResourceCreatedResponse' security: - api-key: [] /api/agents/{agent_id}/tools/{tool_id}: parameters: - in: path name: agent_id description: '' schema: type: string format: uuid required: true - in: path name: tool_id description: '' schema: type: string format: uuid required: true delete: summary: Delete tool by id description: '' operationId: DeleteAgentTool tags: [] parameters: [] responses: '202': content: application/json: schema: $ref: '#/components/schemas/ResourceDeletedResponse' security: - api-key: [] put: summary: Update agent tool definition description: '' operationId: UpdateAgentTool tags: [] parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateToolRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/ResourceUpdatedResponse' security: - api-key: [] patch: summary: Patch Agent tool parameters (merge instead of replace) description: '' operationId: PatchAgentTool tags: [] parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchToolRequest' responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/ResourceUpdatedResponse' security: - api-key: [] /api/jobs/{job_id}: get: summary: Get status of the job description: '' operationId: GetJobStatus tags: [] parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/JobStatus' security: - api-key: [] parameters: - in: path name: job_id description: '' schema: type: string format: uuid required: true components: schemas: User: $schema: http://json-schema.org/draft-04/schema# type: object properties: name: type: string description: Name of the user default: User about: type: string description: About the user created_at: type: string format: date-time description: User created at (RFC-3339 format) updated_at: type: string format: date-time description: User updated at (RFC-3339 format) id: type: string description: User id (UUID) format: uuid metadata: type: object properties: {} description: (Optional) metadata required: - id Agent: $schema: http://json-schema.org/draft-04/schema# type: object properties: name: type: string description: Name of the agent about: type: string description: About the agent default: '' created_at: type: string format: date-time description: Agent created at (RFC-3339 format) updated_at: type: string format: date-time description: Agent updated at (RFC-3339 format) id: type: string description: Agent id (UUID) format: uuid default_settings: $ref: '#/components/schemas/AgentDefaultSettings' description: Default settings for all sessions created by this agent model: type: string description: The model to use with this agent default: julep-ai/samantha-1-turbo metadata: type: object properties: {} description: Optional metadata instructions: oneOf: - type: string - type: array items: type: string description: List of instructions for the agent description: Instructions for the agent required: - name - id - model FunctionParameters: type: object description: The parameters the functions accepts, described as a JSON Schema object. additionalProperties: true properties: {} FunctionDef: type: object properties: description: type: string description: >- A description of what the function does, used by the model to choose when and how to call the function. name: type: string description: >- The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. parameters: $ref: '#/components/schemas/FunctionParameters' description: Parameters accepeted by this function required: - name - parameters Tool: type: object properties: type: type: string enum: - function - webhook description: >- Whether this tool is a `function` or a `webhook` (Only `function` tool supported right now) function: oneOf: - $ref: '#/components/schemas/FunctionDef' description: Function definition and parameters id: type: string description: Tool ID format: uuid required: - type - function - id Session: $schema: http://json-schema.org/draft-04/schema# type: object properties: id: type: string description: Session id (UUID) format: uuid user_id: type: string description: User ID of user associated with this session format: uuid agent_id: type: string description: Agent ID of agent associated with this session format: uuid situation: type: string description: A specific situation that sets the background for this session summary: type: string description: >- (null at the beginning) - generated automatically after every interaction created_at: type: string format: date-time description: Session created at (RFC-3339 format) updated_at: type: string format: date-time description: Session updated at (RFC-3339 format) metadata: type: object properties: {} description: Optional metadata render_templates: type: boolean description: Render system and assistant message content as jinja templates default: false required: - id - user_id - agent_id CreateUserRequest: $schema: http://json-schema.org/draft-04/schema# type: object properties: name: type: string description: Name of the user default: User about: type: string description: About the user docs: type: array items: $ref: '#/components/schemas/CreateDoc' description: Snippet that has information about the user description: List of docs about user metadata: type: object properties: {} description: (Optional) metadata description: A valid request payload for creating a user CreateSessionRequest: $schema: http://json-schema.org/draft-04/schema# type: object properties: user_id: type: string description: (Optional) User ID of user to associate with this session format: uuid agent_id: type: string description: Agent ID of agent to associate with this session format: uuid situation: type: string description: A specific situation that sets the background for this session metadata: type: object properties: {} description: Optional metadata render_templates: type: boolean description: Render system and assistant message content as jinja templates default: false required: - agent_id description: A valid request payload for creating a session CreateAgentRequest: $schema: http://json-schema.org/draft-04/schema# type: object properties: name: type: string description: Name of the agent about: type: string description: About the agent default: '' tools: type: array items: $ref: '#/components/schemas/CreateToolRequest' description: >- A list of tools the model may call. Currently, only `function`s are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. default_settings: $ref: '#/components/schemas/AgentDefaultSettings' description: Default model settings to start every session with model: type: string description: Name of the model that the agent is supposed to use default: julep-ai/samantha-1-turbo docs: type: array items: $ref: '#/components/schemas/CreateDoc' description: Snippet that has information about the agent description: List of docs about agent metadata: type: object properties: {} description: (Optional) metadata instructions: oneOf: - type: string - type: array items: type: string description: List of instructions for the agent description: Instructions for the agent required: - name description: A valid request payload for creating an agent UpdateSessionRequest: $schema: http://json-schema.org/draft-04/schema# type: object properties: situation: type: string description: Updated situation for this session metadata: type: object properties: {} description: Optional metadata description: A valid request payload for updating a session required: - situation UpdateAgentRequest: $schema: http://json-schema.org/draft-04/schema# type: object properties: about: type: string description: About the agent name: type: string description: Name of the agent model: type: string description: Name of the model that the agent is supposed to use default_settings: $ref: '#/components/schemas/AgentDefaultSettings' description: Default model settings to start every session with metadata: type: object properties: {} description: Optional metadata instructions: oneOf: - type: string - type: array items: type: string description: List of instructions for the agent description: Instructions for the agent description: A valid request payload for updating an agent required: - about - name UpdateUserRequest: $schema: http://json-schema.org/draft-04/schema# type: object properties: about: type: string description: About the user name: type: string description: Name of the user metadata: type: object properties: {} description: Optional metadata description: A valid request payload for updating a user required: - about - name Suggestion: $schema: http://json-schema.org/draft-04/schema# type: object properties: created_at: type: string description: Suggestion created at (RFC-3339 format) format: date-time target: type: string enum: - user - agent description: Whether the suggestion is for the `agent` or a `user` content: type: string description: The content of the suggestion message_id: type: string description: The message that produced it format: uuid session_id: type: string description: Session this suggestion belongs to format: uuid required: - message_id - target - content - session_id ChatMLMessage: $schema: http://json-schema.org/draft-04/schema# type: object properties: role: type: string enum: - user - assistant - system - function_call - function description: ChatML role (system|assistant|user|function_call|function) content: type: string description: ChatML content name: type: string description: ChatML name created_at: type: string format: date-time description: Message created at (RFC-3339 format) id: type: string description: Message ID format: uuid required: - id - created_at - content - role InputChatMLMessage: $schema: http://json-schema.org/draft-04/schema# type: object properties: role: type: string enum: - user - assistant - system - function_call - function - auto description: ChatML role (system|assistant|user|function_call|function|auto) content: type: string description: ChatML content default: '' name: type: string description: ChatML name continue: type: boolean default: false description: Whether to continue this message or return a new one required: - content - role ChatInputData: type: object properties: messages: description: A list of new input messages comprising the conversation so far. type: array minItems: 1 items: $ref: '#/components/schemas/InputChatMLMessage' tools: type: array nullable: true description: >- (Advanced) List of tools that are provided in addition to agent's default set of tools. Functions of same name in agent set are overriden items: $ref: '#/components/schemas/Tool' tool_choice: nullable: true oneOf: - $ref: '#/components/schemas/ToolChoiceOption' - $ref: '#/components/schemas/NamedToolChoice' description: >- Can be one of existing tools given to the agent earlier or the ones included in the request required: - messages NamedToolChoice: type: object description: >- Specifies a tool the model should use. Use to force the model to call a specific function. properties: type: type: string enum: - function description: The type of the tool. Currently, only `function` is supported. function: type: object properties: name: type: string description: The name of the function to call. required: - name required: - type - function ToolChoiceOption: description: > Controls which (if any) function is called by the model. `none` means the model will not call a function and instead generates a message. `auto` means the model can pick between generating a message or calling a function. Specifying a particular function via `{"type: "function", "function": {"name": "my_function"}}` forces the model to call that function. `none` is the default when no functions are present. `auto` is the default if functions are present. oneOf: - type: string description: > `none` means the model will not call a function and instead generates a message. `auto` means the model can pick between generating a message or calling a function. enum: - none - auto - $ref: '#/components/schemas/NamedToolChoice' type: string FunctionCallOption: type: object description: > Specifying a particular function via `{"name": "my_function"}` forces the model to call that function. properties: name: type: string description: The name of the function to call. required: - name CompletionUsage: type: object description: Usage statistics for the completion request. properties: completion_tokens: type: integer description: Number of tokens in the generated completion. prompt_tokens: type: integer description: Number of tokens in the prompt. total_tokens: type: integer description: Total number of tokens used in the request (prompt + completion). required: - prompt_tokens - completion_tokens - total_tokens ChatResponse: type: object description: >- Represents a chat completion response returned by model, based on the provided input. properties: id: type: string description: A unique identifier for the chat completion. format: uuid finish_reason: type: string description: >- The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence, `length` if the maximum number of tokens specified in the request was reached, `content_filter` if content was omitted due to a flag from our content filters, `tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function. enum: - stop - length - tool_calls - content_filter - function_call response: type: array description: A list of chat completion messages produced as a response. items: type: array properties: items: $ref: '#/components/schemas/ChatMLMessage' items: $ref: '#/components/schemas/ChatMLMessage' usage: $ref: '#/components/schemas/CompletionUsage' jobs: type: array items: type: string format: uuid uniqueItems: true description: IDs (if any) of jobs created as part of this request required: - usage - response - finish_reason - id Memory: $schema: http://json-schema.org/draft-04/schema# type: object properties: agent_id: type: string format: uuid description: ID of the agent user_id: type: string format: uuid description: ID of the user content: type: string description: Content of the memory created_at: type: string format: date-time description: Memory created at (RFC-3339 format) last_accessed_at: type: string format: date-time description: Memory last accessed at (RFC-3339 format) timestamp: type: string description: Memory happened at (RFC-3339 format) format: date-time sentiment: type: number default: 0 minimum: -1 maximum: 1 description: Sentiment (valence) of the memory on a scale of -1 to 1 id: type: string description: Memory id (UUID) format: uuid entities: type: array items: type: object properties: {} description: List of entities mentioned in the memory required: - type - content - created_at - id - agent_id - user_id - entities ChatSettings: type: object properties: frequency_penalty: type: number default: 0 minimum: -1 maximum: 1 nullable: true description: >- (OpenAI-like) Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. length_penalty: type: number default: 1 minimum: 0 maximum: 2 nullable: true description: "(Huggingface-like) Number between 0 and 2.0. 1.0 is neutral and values larger than that penalize number of tokens generated. " logit_bias: type: object default: null nullable: true additionalProperties: type: integer description: > Modify the likelihood of specified tokens appearing in the completion. Accepts a JSON object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token. properties: {} max_tokens: description: > The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. type: integer nullable: true default: 200 minimum: 1 maximum: 16384 presence_penalty: type: number default: 0 minimum: -1 maximum: 1 nullable: true description: >- (OpenAI-like) Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. repetition_penalty: type: number default: 1 minimum: 0 maximum: 2 nullable: true description: >- (Huggingface-like) Number between 0 and 2.0. 1.0 is neutral and values larger than that penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. response_format: type: object description: > An object specifying the format that the model must output. Setting to `{ "type": "json_object" }` enables JSON mode, which guarantees the message the model generates is valid JSON. **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. properties: type: type: string enum: - text - json_object - regex example: json_object default: text description: Must be one of `"text"`, `"regex"` or `"json_object"`. pattern: type: string description: Regular expression pattern to use if `type` is `"regex"` schema: type: object properties: {} default: {} description: JSON Schema to use if `type` is `"json_object"` seed: type: integer minimum: -1 maximum: 9999 nullable: true description: > This feature is in Beta. If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result. Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend. stop: description: | Up to 4 sequences where the API will stop generating further tokens. default: null oneOf: - type: string nullable: true - type: array minItems: 1 maxItems: 4 items: type: string stream: description: > If set, partial message deltas will be sent, like in ChatGPT. Tokens will be sent as data-only [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) as they become available, with the stream terminated by a `data: [DONE]` message. [Example Python code](https://cookbook.openai.com/examples/how_to_stream_completions). type: boolean nullable: true default: false temperature: type: number minimum: 0 maximum: 2 default: 0.75 example: 0.75 nullable: true description: >- What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. top_p: type: number minimum: 0 maximum: 1 default: 1 example: 1 nullable: true description: >- Defaults to 1 An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. exclusiveMinimum: true min_p: type: number description: Minimum probability compared to leading token to be considered exclusiveMaximum: true maximum: 1 exclusiveMinimum: false minimum: 0 example: 0.01 default: 0.01 preset: type: string description: >- Generation preset name (problem_solving|conversational|fun|prose|creative|business|deterministic|code|multilingual) enum: - problem_solving - conversational - fun - prose - creative - business - deterministic - code - multilingual AgentDefaultSettings: type: object properties: frequency_penalty: type: number default: 0 minimum: -2 maximum: 2 nullable: true description: >- (OpenAI-like) Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. length_penalty: type: number default: 1 minimum: 0 maximum: 2 nullable: true description: "(Huggingface-like) Number between 0 and 2.0. 1.0 is neutral and values larger than that penalize number of tokens generated. " presence_penalty: type: number default: 0 minimum: -1 maximum: 1 nullable: true description: >- (OpenAI-like) Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. repetition_penalty: type: number default: 1 minimum: 0 maximum: 2 nullable: true description: >- (Huggingface-like) Number between 0 and 2.0. 1.0 is neutral and values larger than that penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. temperature: type: number minimum: 0 maximum: 3 default: 0.75 example: 0.75 nullable: true description: >- What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. top_p: type: number minimum: 0 maximum: 1 default: 1 example: 1 nullable: true description: >- Defaults to 1 An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. min_p: type: number description: Minimum probability compared to leading token to be considered exclusiveMaximum: true maximum: 1 exclusiveMinimum: false minimum: 0 example: 0.01 default: 0.01 preset: type: string description: >- Generation preset name (one of: problem_solving, conversational, fun, prose, creative, business, deterministic, code, multilingual) enum: - problem_solving - conversational - fun - prose - creative - business - deterministic - code - multilingual ChatInput: allOf: - $ref: '#/components/schemas/ChatInputData' - $ref: '#/components/schemas/ChatSettings' - $ref: '#/components/schemas/MemoryAccessOptions' Doc: type: object properties: title: type: string description: Title describing what this bit of information contains content: type: string description: Information content id: type: string description: ID of doc format: uuid created_at: type: string description: Doc created at format: date-time metadata: type: object properties: {} description: optional metadata required: - title - content - id - created_at CreateDoc: type: object properties: title: type: string description: Title describing what this bit of information contains content: type: string description: Information content metadata: type: object properties: {} description: Optional metadata required: - title - content MemoryAccessOptions: type: object properties: recall: type: boolean description: Whether previous memories should be recalled or not default: true record: type: boolean description: Whether this interaction should be recorded in history or not default: true remember: type: boolean description: Whether this interaction should form memories or not default: true CreateToolRequest: type: object properties: type: type: string enum: - function - webhook description: >- Whether this tool is a `function` or a `webhook` (Only `function` tool supported right now) function: oneOf: - $ref: '#/components/schemas/FunctionDef' description: Function definition and parameters required: - type - function UpdateToolRequest: type: object properties: function: $ref: '#/components/schemas/FunctionDef' description: Function definition and parameters required: - function ResourceCreatedResponse: type: object properties: id: type: string format: uuid created_at: type: string format: date-time jobs: type: array items: type: string format: uuid uniqueItems: true description: IDs (if any) of jobs created as part of this request required: - id - created_at ResourceUpdatedResponse: type: object properties: id: type: string format: uuid updated_at: type: string format: date-time jobs: type: array items: type: string format: uuid description: IDs (if any) of jobs created as part of this request uniqueItems: true required: - id - updated_at ResourceDeletedResponse: type: object properties: id: type: string format: uuid deleted_at: type: string format: date-time jobs: type: array items: type: string format: uuid description: IDs (if any) of jobs created as part of this request uniqueItems: true required: - id - deleted_at JobStatus: $schema: http://json-schema.org/draft-04/schema# type: object properties: name: type: string description: Name of the job reason: type: string description: Reason for current state created_at: type: string format: date-time description: Job created at (RFC-3339 format) updated_at: type: string format: date-time description: Job updated at (RFC-3339 format) id: type: string description: Job id (UUID) format: uuid has_progress: type: boolean default: false description: Whether this Job supports progress updates progress: type: number description: Progress percentage default: 0 minimum: 0 maximum: 100 state: type: string description: >- Current state (one of: pending, in_progress, retrying, succeeded, aborted, failed) enum: - pending - in_progress - retrying - succeeded - aborted - failed - unknown required: - id - name - created_at - state PatchUserRequest: $schema: http://json-schema.org/draft-04/schema# type: object properties: about: type: string description: About the user name: type: string description: Name of the user metadata: type: object properties: {} description: Optional metadata description: A request for patching a user PatchAgentRequest: $schema: http://json-schema.org/draft-04/schema# type: object properties: about: type: string description: About the agent name: type: string description: Name of the agent model: type: string description: Name of the model that the agent is supposed to use default_settings: $ref: '#/components/schemas/AgentDefaultSettings' description: Default model settings to start every session with metadata: type: object properties: {} description: Optional metadata instructions: oneOf: - type: string - type: array items: type: string description: List of instructions for the agent description: Instructions for the agent description: A request for patching an agent PatchSessionRequest: $schema: http://json-schema.org/draft-04/schema# type: object properties: situation: type: string description: Updated situation for this session metadata: type: object properties: {} description: Optional metadata description: A request for patching a session PatchToolRequest: type: object properties: function: $ref: '#/components/schemas/PartialFunctionDef' description: Function definition and parameters required: - function PartialFunctionDef: type: object properties: description: type: string description: >- A description of what the function does, used by the model to choose when and how to call the function. name: type: string description: >- The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. parameters: $ref: '#/components/schemas/FunctionParameters' description: Parameters accepeted by this function securitySchemes: api-key: type: apiKey scheme: basic description: API Key Authentication name: Authorization in: header parameters: session_id: in: path required: false description: '' schema: type: string format: uuid user_id: in: path required: false description: '' schema: type: string format: uuid agent_id: in: path required: false description: '' schema: type: string format: uuid message_id: in: path required: false description: '' schema: type: string format: uuid doc_id: in: path required: false description: '' schema: type: string format: uuid memory_id: in: path required: false description: '' schema: type: string format: uuid tool_id: in: path required: false description: '' schema: type: string format: uuid job_id: in: path required: false description: '' schema: type: string format: uuid requestBodies: {} security: - api-key: []