Give a run files, skills and connections

1. Turn input into blocks

Give input as a list instead of a string. text blocks are joined into the prompt; each image, document or file block is a file the run starts with. The agent finds each one at /workspace/.rush/attachments/<name>, already named in its prompt.

{"harness": "claude", "input": [
  {"type": "text", "text": "Check the logo against the brand guide."},
  {"type": "image", "source": {"type": "url", "url": "https://acme.com/logo.png"}},
  {"type": "document", "name": "guide.pdf",
   "source": {"type": "base64", "media_type": "application/pdf", "data": "JVBERi0..."}}
]}

At least one block must be text. Each block's source says how its bytes arrive:

2. Upload a private file

Name each file and its type with createFiles. Rush answers an upload_url per file:

curl -s -X POST https://api.prix.dev/o/$ORG/files \
  -H "Authorization: Bearer $RUSH_API_KEY" -H "Content-Type: application/json" \
  -d '{"files": [{"name": "demo.mp4", "mime_type": "video/mp4"}]}'

PUT the bytes straight to that URL, with Content-Type set to the file's mime_type:

curl -s -X PUT -H "Content-Type: video/mp4" --upload-file ./demo.mp4 "$DEMO_UPLOAD_URL"

An upload_url is good for an hour, and one call takes up to 50 files. Then pass the returned id:

{"type": "file", "source": {"type": "file", "file_id": "3f0c..."}}

When the run starts, each file's bytes are checked against its type (400 INVALID_BODY if a PNG was sent as a PDF), and a file you never uploaded is 409 ATTACHMENT_NOT_UPLOADED.

3. Add skills

skills takes up to 10 public URLs, each a string or {"url": "..."}:

"skills": ["https://github.com/anthropics/skills/tree/main/skills/frontend-design"]

A URL can be a GitHub tree URL to a directory holding SKILL.md, a URL to a SKILL.md file, a GitHub repository download, or a .zip. Rush fetches each one when the run is created and pins a GitHub source to the commit its branch or tag points at, so a follow-up loads the same skill. An unreachable URL is 422 SKILL_FETCH_FAILED; link the final URL, not one that redirects. No SKILL.md, or skills that pack past 96 KiB, is 422 SKILL_INVALID.

4. Name what the agent may call

connections takes up to 20 entries, each in one of three forms:

"connections": [
  "c0nn3ct10n1d",
  "deepwiki",
  {"url": "https://mcp.exa.ai/mcp", "auth": {"mode": "bearer", "token": "<exa key>"}}
]

• An id from GET /me/connections: an MCP server, or a Google or Microsoft account you connected once.
• A name of one of those, as GET /me/connections lists it: what you named an MCP server, or the provider of an account ("google"). Only your own connections match. A name two of them share is 422 CONNECTION_AMBIGUOUS, which lists their ids; send one id instead.
• An inline MCP server {url, name?, auth?} for this run and its follow-ups only, never saved. The host must resolve to public addresses (422 MCP_SERVER_URL_INVALID). The token is stored encrypted on the run and never comes back.

An id or name that is unknown or still connecting is 422 CONNECTION_NOT_READY. Follow-ups keep all three forms.

A secret is not a connection. Save it to a Project with createSecret and start the run in that Project with createProjectSession; the agent reads it as an environment variable without the run naming it.

5. Put the repository and the issue in front of the agent

resources lists what Rush prepares before the agent starts, each by URL:

"resources": [
  {"url": "https://github.com/acme/web/tree/main"},
  {"url": "https://linear.app/acme/issue/ENG-42"}
]

One repository per run, reached through a Rush GitHub App installation; getGithubConnection lists what it can reach. Add "connection": "<installation id>" when two installations cover the same repository. Any other URL is 422 RESOURCE_UNSUPPORTED. A repository no installation covers, or an issue with no Linear connection, is 422 RESOURCE_NOT_ACCESSIBLE.

6. Send it

curl -X POST https://api.prix.dev/o/$ORG/sessions \
  -H "Authorization: Bearer $RUSH_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "harness": "claude",
    "input": "Add a dark mode toggle to the settings page.",
    "skills": ["https://github.com/anthropics/skills/tree/main/skills/frontend-design"],
    "connections": ["deepwiki"],
    "resources": [{"url": "https://github.com/acme/web/tree/main"},
                  {"url": "https://linear.app/acme/issue/ENG-42"}]
  }'

The answer is 202 with the session, as in the first lesson. Read it later and its attachments list the files it was given, each with a download url good for an hour.

Connections covers connecting an MCP server or an account once, and Run a saved agent from code saves these choices so each run names only the agent and the task.