---
title: "Create native Linc session"
method: POST
path: "/linc/v1/sessions"
tags: ["Agents/Linc"]
---

# Create native Linc session

`POST /linc/v1/sessions`

## Request

- Base URL: `https://api.case.dev`
- URL: `https://api.case.dev/linc/v1/sessions`
- Auth: HTTP bearer

Creates a native Linc session in a sandboxed runtime with scoped Case.dev credentials. This endpoint starts the sandbox actor only; messages and event replay use separate endpoints.

## Headers

- `ai-reporting-user` string
- `ai-reporting-tags` string

## Request body

- object
  - `title` string
  - `model` string, nullable
  - `modelFallbacks` string[]: Optional ordered availability fallbacks for this session. Requires an explicit model. An empty array disables fallbacks; omission preserves existing runtime behavior. Linc switches within the same session, preserving context.
  - `serviceTier` 'default' | 'priority': Processing tier for eligible OpenAI GPT models. Priority provides lower latency at premium cost.
  - `idleTimeoutMs` integer, nullable
  - `workspaceKey` string: Opt-in persistent workspace identity. Requires conversationKey. Omit both fields to preserve isolated legacy session behavior.
  - `conversationKey` string: Stable conversation identity within workspaceKey. Required in workspace mode and idempotent for repeated creates.
  - `runtimeRetentionDays` integer: Days the runtime and its saved state are kept after the last activity. Defaults to 1 for standalone sessions; workspace-mode conversations (workspaceKey) and the C3 system key default to indefinite (see runtimeRetention). Once they are deleted, commands to the session answer 410 linc_runtime_expired; its events stay readable. A workspace keeps the value it was created with; a larger value on a later conversation raises it. Applies to Vercel Sandbox runtimes; accepted and stored on Daytona, where it has no effect. Mutually exclusive with runtimeRetention.
  - `runtimeRetention` 'indefinite': indefinite keeps the runtime and its saved state until the session (or, in workspace mode, its last conversation) is deleted, so a chat can resume after any idle gap. The default in workspace mode; standalone chats opt in with it, one-off runs leave it unset. Raises an existing workspace to indefinite. Mutually exclusive with runtimeRetentionDays.
  - `capabilityPolicy` 'read_only': Optional server-enforced capability profile. read_only grants only retrieval/inference service reads; session event ingestion remains bound to the exact managed runtime credential.
  - `vaultIds` string[], nullable: Legacy explicit whole-vault scope. Mutually exclusive with vaultScopes.
  - `vaultScopes` object[], nullable: Exact object allowlist per vault. Empty objectIds denies object access for that vault. Mutually exclusive with vaultIds.
    - `vaultId` string, required
    - `objectIds` string[], required
  - `scopedApiKey` string, nullable: Optional caller-provided scoped Case.dev API key for the runtime.
  - `instructions` string, nullable: Privileged C3-only hidden app instructions to append to the sandbox AGENTS.md.
  - `skillSlugs` string[], nullable: Skills API slugs to install into the runtime sandbox before the native session starts.
  - `skillsDelivery` 'local' | 'mcp': Defaults to local preinstallation. MCP is an opt-in, org-allowlisted rollout on a separately pinned image; requires a new standalone session and no skillSlugs preinstallation. Execution remains content-approval gated.
  - `includeDocumentTemplates` boolean, nullable: When true, inject all active org document templates into the using-document-templates skill.
  - `documentTemplateSlugs` string[], nullable: Specific document template slugs to inject into the using-document-templates skill.
  - `extensions` object[], nullable: Optional caller-supplied executable tool files to install into .linc/extensions/ before the agent starts. Only supported for standalone sessions without capabilityPolicy: read_only. Rejected with a 400 on persistent (workspaceKey/conversationKey) or read_only sessions. At most 10 files, 64KB each, 256KB total. Extension destinations and content hashes are recorded in the session-created audit event; raw code is not logged.
    - `path` string, required: Bare .ts/.js filename or one-level subdir (e.g. create-automations.ts or automations/index.ts). Each directory must include exactly one index.ts or index.js entrypoint; helper files may accompany it. Platform names (casedev/subagent), root index.ts/index.js, node_modules, hidden top-level names, absolute paths, "..", and other extensions or nesting are rejected.
    - `content` string, required: UTF-8 tool file content, at most 64KB.

## Response `200`

Linc session created

## Other responses

- `202`: Linc session is provisioning. When skillSlugs were requested, `skills` reports exactly what will be preinstalled into the sandbox (loaded) and which slugs did not resolve in the skills registry (missing).
- `400`: Invalid payload
- `401`: Invalid API key
- `403`: No agent access or Linc runtime disabled
- `404`: Vault not found
- `422`: None of the requested skillSlugs resolved in the skills registry (custom or curated)

## Changes

- **2026-10-28** `0342b8b0c63b`: 1 breaking, 2 info
  - the response property `runtimeRetentionDays` became nullable for the status `202`
  - added the new optional request property `runtimeRetention`
  - added the optional property `runtimeRetention` to the response with the `202` status
- **2026-10-22** `67fe26768ee0`: 2 info
  - added the new optional request property `runtimeRetentionDays`
  - added the optional property `runtimeRetentionDays` to the response with the `202` status
- **2026-10-16** `a21d188f4b21`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/casemark/apis/case-dev-api/changes/linc/v1/sessions/post.md)

---

[API](https://skmtc.dev/casemark/apis/case-dev-api.md) - [All operations](https://skmtc.dev/casemark/apis/case-dev-api/llms.txt) - [OpenAPI document](https://skmtc.dev/casemark/apis/case-dev-api/revisions/9a3245c00044?raw)