# Give a run files, skills and connections Start a run with files in its sandbox, skills loaded from a URL, the tools it may call and the repository or issue it works from. A string `input` is enough for a task the agent can do from scratch. Real work usually needs more: a screenshot, a spec, a team's review checklist, an MCP server, the repository and the ticket. In this lesson you build one `POST /o/{org}/sessions` request that carries all of them, one field at a time. Each field below is optional and works on its own. Start from the request in [Your first run from code](/docs/learn/first-api-run). ## Files in the input ### 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/`, already named in its prompt. ```json {"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: | `source.type` | Use it for | Limits | | --- | --- | --- | | `url` | A public `https` file Rush fetches before the run starts | Public addresses, 3 redirects, 60 seconds; a fetch that fails is `422 INPUT_FETCH_FAILED` and no run starts | | `base64` | Small files sent in the request | The whole body is at most 32 MB, else `413 REQUEST_TOO_LARGE` | | `file` | A private file you upload first | Up to 5 GB per file | ### 2. Upload a private file Name each file and its type with [`createFiles`](/docs/api/create-files). Rush answers an `upload_url` per file: ```bash 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`: ```bash 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`: ```json {"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`. ## Skills by URL ### 3. Add skills `skills` takes up to 10 public URLs, each a string or `{"url": "..."}`: ```json "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`. ## Connections ### 4. Name what the agent may call `connections` takes up to 20 entries, each in one of three forms: ```json "connections": [ "c0nn3ct10n1d", "deepwiki", {"url": "https://mcp.exa.ai/mcp", "auth": {"mode": "bearer", "token": ""}} ] ``` - **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`](/docs/api/create-secret) and start the run in that Project with [`createProjectSession`](/docs/api/create-project-session); the agent reads it as an environment variable without the run naming it. ## Resources ### 5. Put the repository and the issue in front of the agent `resources` lists what Rush prepares before the agent starts, each by URL: ```json "resources": [ {"url": "https://github.com/acme/web/tree/main"}, {"url": "https://linear.app/acme/issue/ENG-42"} ] ``` | URL | What Rush does | | --- | --- | | `https://github.com//` | Clones the repository at its default branch | | `.../tree/` | Clones it at that branch | | `.../pull/` | Clones it on that open pull request's branch | | `https://linear.app//issue/` | Puts the issue in the prompt, read through your Linear connection | One repository per run, reached through a Rush GitHub App installation; [`getGithubConnection`](/docs/api/get-github-connection) lists what it can reach. Add `"connection": ""` 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`. ## The whole request ### 6. Send it ```bash 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. ## Next [Connections](/docs/concepts/connections) covers connecting an MCP server or an account once, and [Run a saved agent from code](/docs/learn/saved-agents-from-code) saves these choices so each run names only the agent and the task.