Add a session resource

⚠️

Preview — this feature is being built; the design below is the spec.

POST https://app.syntic.ai/v1/sessions/{session_id}/resources

Mount a file, a Git repository or a memory store into a running or idle session. The mount appears in the session’s environment before the agent’s next turn, and a resource.added event is written to the event log so the agent is told the path exists. Resources added at session creation through the resources field behave the same way.

For how this fits into a full workflow, see Session resources.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer <key>`: a private inference key (`sk_live_...`). See Authentication.
`syntic-beta`	Yes, while in preview	`agents-2026-11-01`. Without it the call fails with `400 beta_required`. See Versioning.
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Up to 255 characters. Retrying with the same key within 24 hours returns the first result instead of acting twice. See Idempotency.

Path parameters

Parameter	Type	Description
`session_id`	string	The session id, starting with `sesn_`.

Body parameters

Parameter	Type	Required	Notes
`kind`	string	Yes	`file`, `git_repository` or `memory_store`.
`file_id`	string	For `file`	A file uploaded with purpose `agent_input`. Up to 500 MB.
`git`	object	For `git_repository`	`url` (HTTPS), `ref` (branch, tag or commit; default branch if left out) and `vault_secret`, the name of a secret in the session’s vault holding a read token.
`memory_store_id`	string	For `memory_store`	Attaches the store’s tools to this session only. The agent’s own stores stay attached.
`mount_path`	string	No	Absolute path under `/workspace`. Defaults to `/workspace/inputs/<filename>` for files and `/workspace/<repo name>` for repositories.
`read_only`	boolean	No	Default `true` for files, `false` for repositories.

Response

201 Created, Content-Type: application/json

{
  "id": "sres_01JCB1D3F5H7K9M1P3R5",
  "type": "session_resource",
  "session_id": "sesn_01JC7M2K4P6R8T0V2X4Z",
  "kind": "file",
  "file_id": "file_01JC3D5F7H9K1M3P5R7T",
  "mount_path": "/workspace/inputs/orders-q3.csv",
  "read_only": true,
  "status": "mounted",
  "error": null,
  "created_at": "2026-11-05T10:01:00Z",
  "updated_at": "2026-11-05T10:01:02Z"
}

Field	Type	Description
`id`	string	Starts with `sres_`.
`kind`	string	`file`, `git_repository` or `memory_store`.
`file_id`	string	For `kind: file`: the Files API id that is mounted.
`git`	object	For `kind: git_repository`: `url`, `ref`, the resolved `commit`, and the vault secret used to clone.
`mount_path`	string	Absolute path under `/workspace` inside the session’s environment.
`read_only`	boolean	Read-only mounts reject writes from the agent’s tools.
`status`	string	`pending`, `mounted`, `failed` or `removed`.
`error`	object or null	Why mounting failed: `code` and `message`.

Examples

curl -sS "https://app.syntic.ai/v1/sessions/sesn_01JC7M2K4P6R8T0V2X4Z/resources" \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "syntic-beta: agents-2026-11-01" \
  -H "Idempotency-Key: 8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69" \
  -H "Content-Type: application/json" \
  -d '{
      "kind": "file",
      "file_id": "file_01JC3D5F7H9K1M3P5R7T",
      "mount_path": "/workspace/inputs/orders-q3.csv"
    }'

import os
 
import requests
 
resp = requests.post(
    "https://app.syntic.ai/v1/sessions/sesn_01JC7M2K4P6R8T0V2X4Z/resources",
    headers={
        "Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}",
        "syntic-beta": "agents-2026-11-01",
        "Idempotency-Key": "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69",
    },
    json={
        "kind": "file",
        "file_id": "file_01JC3D5F7H9K1M3P5R7T",
        "mount_path": "/workspace/inputs/orders-q3.csv"
    },
    timeout=60,
)
data = resp.json()
if not resp.ok:
    raise RuntimeError(f"{resp.status_code} {data['error']['code']}: {data['error']['message']}")
print(data)

const res = await fetch('https://app.syntic.ai/v1/sessions/sesn_01JC7M2K4P6R8T0V2X4Z/resources', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNTIC_API_KEY}`,
    'syntic-beta': 'agents-2026-11-01',
    'Idempotency-Key': '8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "kind": "file",
    "file_id": "file_01JC3D5F7H9K1M3P5R7T",
    "mount_path": "/workspace/inputs/orders-q3.csv"
  }),
})
const text = await res.text()
const data = text ? JSON.parse(text) : null
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`)
console.log(data ?? res.status)

package main
 
import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)
 
func main() {
	body := strings.NewReader(`{
  "kind": "file",
  "file_id": "file_01JC3D5F7H9K1M3P5R7T",
  "mount_path": "/workspace/inputs/orders-q3.csv"
}`)
	req, err := http.NewRequest("POST", "https://app.syntic.ai/v1/sessions/sesn_01JC7M2K4P6R8T0V2X4Z/resources", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SYNTIC_API_KEY"))
	req.Header.Set("syntic-beta", "agents-2026-11-01")
	req.Header.Set("Idempotency-Key", "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69")
	req.Header.Set("Content-Type", "application/json")
 
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
 
	out, _ := io.ReadAll(resp.Body)
	if resp.StatusCode >= 300 {
		panic(fmt.Sprintf("%d: %s", resp.StatusCode, out))
	}
	fmt.Println(string(out))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
public class Example {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "kind": "file",
              "file_id": "file_01JC3D5F7H9K1M3P5R7T",
              "mount_path": "/workspace/inputs/orders-q3.csv"
            }
            """;
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://app.syntic.ai/v1/sessions/sesn_01JC7M2K4P6R8T0V2X4Z/resources"))
            .header("Authorization", "Bearer " + System.getenv("SYNTIC_API_KEY"))
            .header("syntic-beta", "agents-2026-11-01")
            .header("Idempotency-Key", "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69")
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 300) {
            throw new RuntimeException(response.statusCode() + ": " + response.body());
        }
        System.out.println(response.body());
    }
}

using System.Net.Http.Headers;
using System.Text;
 
using var http = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("POST"), "https://app.syntic.ai/v1/sessions/sesn_01JC7M2K4P6R8T0V2X4Z/resources");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("SYNTIC_API_KEY"));
request.Headers.Add("syntic-beta", "agents-2026-11-01");
request.Headers.Add("Idempotency-Key", "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69");
request.Content = new StringContent("""
    {
      "kind": "file",
      "file_id": "file_01JC3D5F7H9K1M3P5R7T",
      "mount_path": "/workspace/inputs/orders-q3.csv"
    }
    """, Encoding.UTF8, "application/json");
 
using var response = await http.SendAsync(request);
var text = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode) throw new Exception($"{(int)response.StatusCode}: {text}");
Console.WriteLine(text);

<?php
$body = <<<'JSON'
{
  "kind": "file",
  "file_id": "file_01JC3D5F7H9K1M3P5R7T",
  "mount_path": "/workspace/inputs/orders-q3.csv"
}
JSON;
 
$ch = curl_init('https://app.syntic.ai/v1/sessions/sesn_01JC7M2K4P6R8T0V2X4Z/resources');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SYNTIC_API_KEY'),
        'syntic-beta: agents-2026-11-01',
        'Idempotency-Key: 8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
 
if ($status >= 300) {
    throw new RuntimeException("$status: $response");
}
print_r(json_decode($response, true) ?? $status);

require "json"
require "net/http"
require "uri"
 
uri = URI("https://app.syntic.ai/v1/sessions/sesn_01JC7M2K4P6R8T0V2X4Z/resources")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch('SYNTIC_API_KEY')}"
req["syntic-beta"] = "agents-2026-11-01"
req["Idempotency-Key"] = "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69"
req["Content-Type"] = "application/json"
req.body = <<~'JSON'
  {
    "kind": "file",
    "file_id": "file_01JC3D5F7H9K1M3P5R7T",
    "mount_path": "/workspace/inputs/orders-q3.csv"
  }
JSON
 
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
raise "#{res.code}: #{res.body}" unless res.is_a?(Net::HTTPSuccess)
puts res.body.empty? ? res.code : JSON.pretty_generate(JSON.parse(res.body))

Errors

Errors use the error envelope and carry a request_id. Codes specific to this operation:

Status	`type`	`code`	When
400	`invalid_request_error`	`beta_required`	The `syntic-beta` header is missing.
400	`invalid_request_error`	`invalid_mount_path`	The path is outside `/workspace` or already used by another resource.
400	`invalid_request_error`	`file_purpose_mismatch`	The file was not uploaded with purpose `agent_input`.
409	`conflict_error`	`resource_limit_reached`	The session already has 50 resources.
409	`conflict_error`	`session_archived`	Archived sessions are read-only.
404	`not_found_error`	`session_not_found`	No session with this id in the key’s workspace.
401	`authentication_error`	`invalid_api_key`	The key is missing, unknown, revoked or expired.
429	`rate_limit_error`	`rate_limited`	Too many requests; wait for `Retry-After`. See Rate-limit headers.

Repositories are cloned shallowly (depth 50). A clone that takes longer than 120 seconds fails with status: failed and error.code: clone_timeout; the session keeps running without it.

Delete List resources

Was this page helpful?