Scout API Update

The Scout core team has spent the last few months reworking how Drive functions. What started as a simple file storage layer has evolved into something closer to a real file system — you can create folders, rename items, move files around, and generally work with it the way you'd expect.

At the same time, we've been thinking about how developers interact with Scout agents from their own code. These powerful agents run code, connect to Salesforce and HubSpot, and orchestrate complex workflows. But, until now, calling them from external applications meant building custom integrations or wrestling with our internal APIs.

We wanted a cleaner path, so we shipped two new API endpoints that let you manage agents and upload files programmatically, without having to touch the dashboard.

Agents' API

This new feature means that you can now call Scout agents directly from your own code. No more custom workflows or workarounds — just send a message and get a response.

Interact with an agent

This is the endpoint we've been asked about the most. Your Scout agents can run code, connect to Salesforce and HubSpot, and arrange multistep workflows, but now you can invoke all of that from your own applications.

Streaming response (/world/{agent_id}/_interact):

from scoutos import Scout, IncomingMessage

client = Scout(api_key="YOUR_API_KEY")

response = client.agents.interact(
    agent_id="your-agent-id",
    messages=[
        IncomingMessage(content="What's the status of order #12345?")
    ]
)

for chunk in response:
    print(chunk)

Synchronous response (/world/{agent_id}/_interact_sync):

response = client.agents.interact_sync(
    agent_id="your-agent-id",
    messages=[
        IncomingMessage(content="Pull the latest Salesforce opportunities")
    ]
)

print(response)

Which response you use depends on your use case. The streaming endpoint is better for long-running agent workflows where you want to show progress, while the synchronous endpoint is simpler for quick queries where you just want the final result.

Both endpoints support a session_id parameter if you want to maintain conversation context across multiple calls.

curl -X POST https://api.scoutos.com/world/{agent_id}/_interact_sync \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"content":"Summarize the latest HubSpot deals"}]}'

Managing agents

You can also list, retrieve, create, and update agents programmatically. This unlocks several workflows:

• CI/CD pipelines: Push a new revision with activate=false, run tests, and then promote.
• Multienvironment setups: Spin up dev, staging, and prod agents from the same configuration.
• Internal tooling: Build dashboards that manage your organization's agents.

from scoutos import Scout

client = Scout(api_key="YOUR_API_KEY")

# List all agents
agents = client.agents.list()

# Get an agent's current configuration
agent = client.agents.get_active(agent_id="your-agent-id")

Full management docs: Agents API

Drive Upload API

The new Drive endpoints let you upload files programmatically in single files or batches. This pairs well with the agents' API: you can upload a knowledge base, and then point your agent at it.

Basic upload

curl -X POST https://api.scoutos.com/drive/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "files[]=@project-proposal.pdf" \
  -F "files[]=@team-photo.jpg"

Upload with metadata

The metadata parameter lets you control where files land. Pass a JSON string with per-file configurations, aligned positionally with your files:

curl -X POST https://api.scoutos.com/drive/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "files[]=@report.pdf" \
  -F "files[]=@data.csv" \
  -F 'metadata=[{"path":"/reports/q1-report.pdf"},{"folder":"/data","name":"sales.csv"}]'

Path resolution works like this:

Response

Each uploaded file returns its ID, final path, and download URL:

{
  "data": [
    {
      "id": "file-12345",
      "name": "report.pdf",
      "path": "/reports/q1-report.pdf",
      "url": "https://drive.scoutos.com/files/12345/download"
    },
    {
      "id": "file-67890",
      "name": "sales.csv",
      "path": "/data/sales.csv",
      "url": "https://drive.scoutos.com/files/67890/download"
    }
  ]
}

Authentication

All endpoints use bearer token authentication:

Authorization: Bearer YOUR_API_KEY

Base URL: https://api.scoutos.com

With the Python SDK, pass your key when initializing the client:

from scoutos import Scout

client = Scout(api_key="YOUR_API_KEY")

Quick reference

Full docs: Agent Interact | Agent Interact Sync | Drive Upload

Questions? Slack or drop us a line.