Upload a file

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v1/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@example-file \
  --form expires_in_seconds=0 \
  --form 'metadata=<string>'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v1/files"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "expires_in_seconds": "0",
    "metadata": "<string>"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('expires_in_seconds', '0');
form.append('metadata', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.recursion.labelbox.com/managed-agents/v1/files', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.recursion.labelbox.com/managed-agents/v1/files",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"expires_in_seconds\"\r\n\r\n0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.recursion.labelbox.com/managed-agents/v1/files"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"expires_in_seconds\"\r\n\r\n0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.recursion.labelbox.com/managed-agents/v1/files")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"expires_in_seconds\"\r\n\r\n0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v1/files")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"expires_in_seconds\"\r\n\r\n0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"\r\n\r\n<string>\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "byte_size": 0,
  "created_at": "2023-11-07T05:31:56Z",
  "downloadable": true,
  "file_id": "<string>",
  "filename": "<string>",
  "media_type": "<string>",
  "organization_id": "<string>",
  "sha256": "<string>",
  "source": "upload",
  "type": "file",
  "expires_at": "2023-11-07T05:31:56Z",
  "metadata": {},
  "ownerAgentId": "<string>",
  "producerAgentVersionId": "<string>",
  "producerSessionId": "<string>",
  "scope_session_id": "<string>"
}

{
  "code": "invalid_json",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "unauthorized",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "forbidden",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "not_found",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "file_quota_exceeded",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "unsupported_media_type",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "rate_limit_exceeded",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "internal_error",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "bad_gateway",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "file_storage_unconfigured",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "gateway_timeout",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

Files

Upload a file

Stores a file the organization can attach to any number of sessions. Attaching one mounts it read-only into the session’s sandbox under its files directory, and the agent knows where to find it. Send the bytes as the file part of a multipart/form-data body; the part’s filename and Content-Type become the file’s name and media type. The file part may contain at most 30 MiB, and the complete multipart request may use at most 128 KiB more for framing and form fields. Larger files are not supported by this Platform V1 operation. The bytes are served back through GET /managed-agents/v1/files//content to the same organization. A request over the transport limit answers 413 with code payload_too_large. An upload that would carry the organization’s live files past its storage quota answers 413 with code file_quota_exceeded and reports the quota, bytes in use, and incoming size in details.

POST

managed-agents

files

Upload a file

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v1/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@example-file \
  --form expires_in_seconds=0 \
  --form 'metadata=<string>'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v1/files"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "expires_in_seconds": "0",
    "metadata": "<string>"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('expires_in_seconds', '0');
form.append('metadata', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.recursion.labelbox.com/managed-agents/v1/files', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.recursion.labelbox.com/managed-agents/v1/files",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"expires_in_seconds\"\r\n\r\n0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.recursion.labelbox.com/managed-agents/v1/files"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"expires_in_seconds\"\r\n\r\n0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.recursion.labelbox.com/managed-agents/v1/files")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"expires_in_seconds\"\r\n\r\n0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v1/files")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"expires_in_seconds\"\r\n\r\n0\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"\r\n\r\n<string>\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "byte_size": 0,
  "created_at": "2023-11-07T05:31:56Z",
  "downloadable": true,
  "file_id": "<string>",
  "filename": "<string>",
  "media_type": "<string>",
  "organization_id": "<string>",
  "sha256": "<string>",
  "source": "upload",
  "type": "file",
  "expires_at": "2023-11-07T05:31:56Z",
  "metadata": {},
  "ownerAgentId": "<string>",
  "producerAgentVersionId": "<string>",
  "producerSessionId": "<string>",
  "scope_session_id": "<string>"
}

{
  "code": "invalid_json",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "unauthorized",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "forbidden",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "not_found",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "file_quota_exceeded",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "unsupported_media_type",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "rate_limit_exceeded",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "internal_error",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "bad_gateway",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "file_storage_unconfigured",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "gateway_timeout",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

Authorizations

Authorization

string

header

required

A Recursion API key, created in the console under API keys.

Headers

x-tenant-id

string

Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.

Minimum string length: 1

x-organization-id

string

Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or default.

Minimum string length: 1

Body

multipart/form-data

Multipart body for uploading a file. Send the bytes as the file part; the part's filename and Content-Type become the file's name and media type.

file

required

The file's bytes. Its part filename is the name the file is stored and mounted under; its part Content-Type is recorded as the media type. The file part may contain at most 30 MiB; larger files are not supported by this Platform V1 operation.

expires_in_seconds

integer<int64>

How long the file stays attachable and its content served, from 3600 (an hour) to 7776000 (ninety days); its metadata stays readable, with expires_at in the past, for a grace after that. Omit for a file that does not expire. Set once: a file's expiry cannot be changed.

Required range: -9007199254740991 <= x <= 9007199254740991

metadata

string

Caller-owned key/value data as a JSON object, since a form part cannot carry structure. Rejected rather than dropped when it does not parse.

Response

A file object: bytes uploaded once and attachable to any number of sessions as a resource, or bytes a session produced. Attaching a file mounts it read-only into the session's sandbox at a path the session is told about.

byte_size

integer<int64>

required

Size of the file in bytes.

Required range: -9007199254740991 <= x <= 9007199254740991

created_at

string<date-time>

required

Server-assigned RFC 3339 timestamp of the upload.

downloadable

boolean

required

Whether GET /managed-agents/v1/files/{fileId}/content serves the bytes. True for every live file, upload or session output; expiry, not source, is what closes the content route.

file_id

string

required

Server-assigned id, used to attach the file to a session as a resource.

filename

string

required

The name the file was uploaded under, without any directory. This is the name it is mounted under in a sandbox unless a resource says otherwise.

media_type

string

required

The upload's declared Content-Type. When the part declared none, or declared application/octet-stream, the type is detected from the filename's extension, through a fixed table rather than the host's, and then from the bytes, falling back to application/octet-stream when neither says anything. Informational: the platform does not transcode or validate against it.

organization_id

string

required

Organization that owns the file. Server-assigned from the caller's credentials.

sha256

string

required

SHA-256 of the file's contents, for checking a download.

source

enum<string>

required

How the file came to exist: upload for a file you uploaded, session_output for a deliverable a session saved.

Available options:

upload,

session_output

type

enum<string>

required

Always file.

Available options:

file

expires_at

string<date-time>

When the file stops being attachable and its content stops being served. Its metadata stays readable and listed, with this in the past, for a grace before the file is reclaimed. Absent means it does not expire.

metadata

object

Caller-owned key/value data stored with the file and returned unchanged.

Show child attributes

ownerAgentId

string

For a session output, the agent whose file history holds it: the agent the root session ran, including outputs its subagents and teammates saved. Absent on uploads and on outputs of sessions not started from an agent.

producerAgentVersionId

string

For a session output, the agent version the writing session ran. Absent for outputs saved before it was recorded.

producerSessionId

string

For a session output, the session in the tree that wrote it, which is a subagent or teammate when not the root.

scope_session_id

string

For a session output, the session that produced it. Absent on an upload, which belongs to the organization rather than to any one session.

API reference

Endpoints

Upload a file

Authorizations

Headers

Body

Response