Store Knowledge - Osmosis API

POST

store_knowledge

curl --request POST \
  --url https://osmosis.gulp.dev/store_knowledge \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "tenant_id": "webarena",
  "query": "Find and purchase a red Nike running shoe in size 10",
  "turns": [
    {
      "turn": 1,
      "inputs": "On shopping website homepage. Need to search for red Nike running shoes.",
      "decision": "{'\''action_type'\'': '\''click'\'', '\''element_name'\'': '\''search_bar'\'', '\''text'\'': ['\''Nike red running shoes'\''], '\''element_role'\'': '\''searchbox'\'', '\''coords'\'': [120, 35], '\''url'\'': '\''https://shop.example.com'\''}",
      "result": "click [120, 35] where [120, 35] is searchbox '\''Search products...'\'' followed by typing '\''Nike red running shoes'\''",
      "memory": "User wants red Nike running shoes. Starting search from homepage."
    },
    {
      "turn": 2,
      "inputs": "Search results show multiple Nike running shoes. Need to select size 10 in red.",
      "decision": "{'\''action_type'\'': '\''click'\'', '\''element_name'\'': '\''product_link'\'', '\''text'\'': ['\''Nike Air Zoom Pegasus - Red'\''], '\''element_role'\'': '\''link'\'', '\''coords'\'': [250, 320], '\''url'\'': '\''https://shop.example.com/products/nike-air-zoom-pegasus?color=red&size=10'\''}",
      "result": "click [250, 320] where [250, 320] is link '\''Nike Air Zoom Pegasus - Red'\'' in size 10 with 4.8/5 stars (2,453 reviews)",
      "memory": "Selected Pegasus model in red, size 10 based on positive reviews and exact match to requirements"
    }
  ],
  "success": "true",
  "agent_type": "browser",
  "timestamp": "2024-03-14T10:30:00Z",
  "metadata": {
    "browser_type": "chrome",
    "site": "shopping_admin",
    "interaction_duration_seconds": 120,
    "user_satisfaction_score": 0.95
  }
}'

{}

The /store_knowledge endpoint allows you to store agent interactions and experiences for future task enhancement.

This endpoint should be used whenever an agent is complete with a task. If your agent spawns sub sub agents, each sub task agent should also call this endpoint once it’s complete.

Base URL

POST https://osmosis.gulp.dev/store_knowledge

Authentication

Request Body

Root Level Parameters

tenant_id

string

required

Unique identifier that corresponds to a dedicated recommendation collection, enabling sub-tenancy isolation for different agentic workflows

query

string

required

The original user query or instruction that initiated the interaction

turns

array

required

Array of interaction turns between the agent and the environment/user

success

boolean

Indicates whether the agent completed its task successfully

agent_type

string

Specifies the type of agent (e.g., ‘browser’, ‘voice’)

timestamp

string

required

When the interaction occurred (ISO format)

metadata

object

Additional metadata about the interaction

Turn Object Structure

Each turn in the turns array represents a single interaction step and contains the following fields:

turn

number

required

The turn number in the interaction sequence. Must start at 1 and be sequential without gaps. For single-turn agents, this should be 1.

inputs

string

required

The flattened input the agent sees at this turn. Should include:

Available tools and options
Current observations
Each tool/option should be listed on a new line

decision

string

required

The output or action taken by the agent during this turn

memory

string

What the agent remembers from this turn, such as:

Values returned from a RAG store
User intent understanding
Key context or decisions made

result

string

The outcome of the agent’s action, including:

User interruptions
Action success/failure
Any deterministic results

Example Requests

curl -X POST https://osmosis.gulp.dev/store_knowledge \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "tenant_id": "your-api-key",
    "query": "Find and purchase a red Nike running shoe in size 10",
    "turns": [
      {
        "turn": 1,
        "inputs": "On shopping website homepage. Need to search for red Nike running shoes.",
        "decision": "{\\"action_type\\": \\"click\\", \\"element_name\\": \\"search_bar\\", \\"text\\": [\\"Nike red running shoes\\"], \\"element_role\\": \\"searchbox\\", \\"coords\\": [120, 35], \\"url\\": \\"https://shop.example.com\\"}",
        "result": "completed_successfully",
        "memory": "User wants red Nike running shoes. Starting search from homepage."
      }
    ],
    "success": true,
    "agent_type": "browser",
    "timestamp": "2024-03-14T10:30:00Z",
    "metadata": {
      "browser_type": "chrome",
      "site": "shopping_admin",
      "interaction_duration_seconds": 120
    }
  }'

Response

Success Response

status

string

required

Status of the request (will be “accepted”)

message

string

required

Human-readable status message

tenant_id

string

required

The tenant ID that was used for the request

Example success response:

{
  "status": "accepted",
  "message": "Knowledge upload queued for processing",
  "tenant_id": "api_key"
}

Error Response

code

string

required

Error code identifying the type of error

status

number

required

HTTP status code

message

string

required

Human-readable error message

details

object

Additional error details when available

Example error response:

{
  "code": "validation_error",
  "status": 400,
  "message": "Invalid request body",
  "details": {
    "field": "turns",
    "error": "Must have at least one turn"
  }
}

Status Codes

Error Codes

Code	Description
`validation_error`	Request validation failed
`invalid_query`	Invalid or missing query
`invalid_turns`	Invalid turns array
`invalid_metadata`	Invalid metadata format
`storage_error`	Error storing knowledge
`internal_error`	Internal server error

Best Practices

Turn Numbers
- Ensure turn numbers are sequential
- Always start from 1
- Avoid gaps in the sequence
- For single-turn agents, use turn number 1
Input Documentation
- Document all available tools and options in the inputs field
- List each tool/option on a new line
- Include relevant observations and context
Memory Management
- Use the memory field to track important context
- Include relevant RAG results
- Document key decisions and user intent

Authorizations

x-api-key

string

header

required

Body

application/json

Agent interaction knowledge to store

Response

202

application/json

Successful Response

The response is of type object.

Enhance Task Delete by Intent

curl --request POST \
  --url https://osmosis.gulp.dev/store_knowledge \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "tenant_id": "webarena",
  "query": "Find and purchase a red Nike running shoe in size 10",
  "turns": [
    {
      "turn": 1,
      "inputs": "On shopping website homepage. Need to search for red Nike running shoes.",
      "decision": "{'\''action_type'\'': '\''click'\'', '\''element_name'\'': '\''search_bar'\'', '\''text'\'': ['\''Nike red running shoes'\''], '\''element_role'\'': '\''searchbox'\'', '\''coords'\'': [120, 35], '\''url'\'': '\''https://shop.example.com'\''}",
      "result": "click [120, 35] where [120, 35] is searchbox '\''Search products...'\'' followed by typing '\''Nike red running shoes'\''",
      "memory": "User wants red Nike running shoes. Starting search from homepage."
    },
    {
      "turn": 2,
      "inputs": "Search results show multiple Nike running shoes. Need to select size 10 in red.",
      "decision": "{'\''action_type'\'': '\''click'\'', '\''element_name'\'': '\''product_link'\'', '\''text'\'': ['\''Nike Air Zoom Pegasus - Red'\''], '\''element_role'\'': '\''link'\'', '\''coords'\'': [250, 320], '\''url'\'': '\''https://shop.example.com/products/nike-air-zoom-pegasus?color=red&size=10'\''}",
      "result": "click [250, 320] where [250, 320] is link '\''Nike Air Zoom Pegasus - Red'\'' in size 10 with 4.8/5 stars (2,453 reviews)",
      "memory": "Selected Pegasus model in red, size 10 based on positive reviews and exact match to requirements"
    }
  ],
  "success": "true",
  "agent_type": "browser",
  "timestamp": "2024-03-14T10:30:00Z",
  "metadata": {
    "browser_type": "chrome",
    "site": "shopping_admin",
    "interaction_duration_seconds": 120,
    "user_satisfaction_score": 0.95
  }
}'

{}

API Reference

​Base URL

​Authentication

​Request Body

​Root Level Parameters

​Turn Object Structure

​Example Requests

​Response

​Success Response

​Error Response

​Status Codes

​Error Codes

​Best Practices

Authorizations

Body

Response

Base URL

Authentication

Request Body

Root Level Parameters

Turn Object Structure

Example Requests

Response

Success Response

Error Response

Status Codes

Error Codes

Best Practices