POST
/
store_knowledge
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

CodeDescription
validation_errorRequest validation failed
invalid_queryInvalid or missing query
invalid_turnsInvalid turns array
invalid_metadataInvalid metadata format
storage_errorError storing knowledge
internal_errorInternal server error

Best Practices

  1. Turn Numbers
    • Ensure turn numbers are sequential
    • Always start from 1
    • Avoid gaps in the sequence
    • For single-turn agents, use turn number 1
  2. 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
  3. 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.