API v1

OpenAPI 3.1

CLI ready

Build with the CLYC API

Use personal API tokens to connect the CLYC CLI, trusted agents, and external automation to project files, uploads, comments, versions, and share links.

Start with the API OpenAPI JSON

Authenticated request

curl -sS https://app.clyc.io/api/cli/v1/me \
  -H "Authorization: Bearer $CLYC_API_TOKEN"

{
  "user": {
    "id": "31a03e74-...",
    "email": "user@company.com"
  },
  "token": {
    "id": "token-id",
    "prefix": "clyc_..."
  }
}

Personal API tokens

Tokens authenticate as the issuing user and inherit current app permissions on every request.

Signed uploads

Direct and multipart upload flows issue short-lived storage URLs after permission checks.

Version-aware comments

List or create comments against an item, a specific version id, or a version number.

Share links

Resolve Notion-stored CLYC links, create/update links, and control comments, download, and embed settings.

Quickstart

From token to first request

Create a token in Personal Settings, store it in your environment, and call the versioned API.

Step 1

Create token

Personal Settings -> API Tokens

Step 2

Install CLI

curl .../install.sh | sh

Step 3

Call API

GET /api/cli/v1/projects

export CLYC_API_URL=https://app.clyc.io
export CLYC_API_TOKEN=clyc_...

curl -sS "$CLYC_API_URL/api/cli/v1/projects" \
  -H "Authorization: Bearer $CLYC_API_TOKEN"

Authentication

Bearer tokens that inherit app permissions

Tokens authenticate as the issuing user. They do not carry separate scopes; the server checks the user's current product permissions for every request.

Token lifecycle

Created and revealed in Personal Settings
Stored as SHA-256 lookup hash plus encrypted token copy
Revoked tokens stop working immediately

Request validation

Authorization header must use Bearer scheme
Token must not be expired or revoked
Last-use metadata and audit rows are recorded

Permissions

Same access as the product

The CLI/API surface is intentionally aligned with existing app permissions to avoid mismatches between UI access and automation access.

Area	Action	Required permission
Resolver	Resolve CLYC links and stable ids	Matching resource permission
Projects	Read one project	projects.view
Items	List, search, inspect, download, versions	items.view
Items	Upload, rename, move, restore, soft delete	items.manage
Items	Permanent delete from trash	items.manage + projects.manage
Comments	Create comments	comments.manage
Comments	Edit own content	comment author
Shares	Resolve share URLs	items.view
Shares	Create, update, delete share links	items.manage

CLI install

Install clyc from the app

The app serves the official CLI executable and a small macOS/Linux installer, so teammates can set up without GitHub or repository access.

curl -fsSL https://app.clyc.io/api/developer/cli/install.sh | sh
clyc skills update --target all
clyc auth login --api-url https://app.clyc.io --token clyc_...
clyc me

Requirements

Node.js 18.18 or newer
curl available in the shell
~/.local/bin on PATH

install.sh clyc.mjs

GET/api/developer/cli/install.shmacOS/Linux install script

GET/api/developer/cli/clyc.mjsRaw Node.js CLI executable

CLI

Scriptable commands over the API

The CLI is a thin JSON client for agents and automation. Environment variables work well for CI, local scripts, and agent sessions.

clyc auth login --api-url https://app.clyc.io --token clyc_...
clyc projects list --search "Kolakov"
clyc resolve "https://app.clyc.io/home/acme/file/..."
clyc files upload <project-id> ./video.mov
clyc files download "https://app.clyc.io/share/..." --output ./downloads/video.mov
clyc comments list "https://app.clyc.io/share/..." --version-number 2
clyc shares create <item-id> --allow-embed true

Agent skill

Install the CLYC skill from the app

Codex, Claude, and team agents can fetch a portable SKILL.md bundle from this API docs surface. No GitHub or repository access is required.

Portable

Uses the standard SKILL.md structure
Keeps detailed command docs in references
Works from the live app domain

CLI-first

Instructs agents to use clyc commands first
Falls back to HTTP only when needed
Preserves JSON outputs for automation

Production-aware

Treats tokens as secrets
Confirms risky mutations
Verifies changed resources after writes

Skill manifest SKILL.md

Install or update

curl -fsSL https://app.clyc.io/api/developer/skills/clyc-cli/install.sh | sh
clyc skills status

# Codex only
curl -fsSL https://app.clyc.io/api/developer/skills/clyc-cli/install.sh | CLYC_SKILL_TARGETS=codex sh

# Claude only
curl -fsSL https://app.clyc.io/api/developer/skills/clyc-cli/install.sh | CLYC_SKILL_TARGETS=claude sh

GET/api/developer/skills/clyc-cliSkill manifest with file URLs

GET/api/developer/skills/clyc-cli/install.shIdempotent skill install/update script

GET/api/developer/skills/clyc-cli/files/SKILL.mdMain skill instructions

GET/api/developer/skills/clyc-cli/files/references/commands.mdCLI command map

GET/api/developer/skills/clyc-cli/files/references/safety.mdProduction safety notes

API reference

Versioned REST endpoints

All CLI API endpoints are rooted under /api/cli/v1 and return JSON responses.

Identity and projects

GET/meCurrent user and token metadata

GET/resolveResolve CLYC URL or id

GET/accountsAccount memberships

GET/projectsAccessible projects

GET/projects/{projectId}Project detail

Files, folders, versions

GET/projects/{projectId}/itemsList or search project items

POST/projects/{projectId}/foldersCreate folder

GET/items/{itemId}Item detail

PATCH/items/{itemId}Rename, move, or update metadata

DELETE/items/{itemId}Soft or permanent delete

POST/items/{itemId}/restoreRestore from trash

GET/items/{itemId}/downloadCreate signed download URL

GET/items/{itemId}/versionsList versions

Comments and shares

GET/items/{itemId}/commentsList comments by item/version

POST/items/{itemId}/commentsCreate comment

PATCH/comments/{commentId}Edit or resolve comment

DELETE/comments/{commentId}Delete comment

GET/items/{itemId}/sharesList share links

POST/items/{itemId}/sharesCreate or reuse share link

GET/shares/resolveResolve share URL to item or container

PATCH/shares/{shareId}Update share link

DELETE/shares/{shareId}Delete share link

Uploads

Direct and multipart storage flows

The API signs storage operations after validating permissions. The CLI automatically chooses multipart uploads above 100 MB.

Direct upload

1Create signed upload URL
2PUT bytes to storage
3Complete upload and create item

Multipart upload

1Create upload session
2Sign part URLs in batches
3PUT each part and collect ETags
4Complete session and create item

POST/projects/{projectId}/uploads/directCreate direct upload URL

POST/projects/{projectId}/uploads/direct/completeFinalize direct upload

POST/projects/{projectId}/uploads/multipartCreate multipart upload

POST/projects/{projectId}/uploads/multipart/partsSign part URLs

POST/projects/{projectId}/uploads/multipart/completeFinalize multipart upload

POST/items/{itemId}/versions/uploads/directCreate version upload URL

POST/items/{itemId}/versions/uploads/multipartCreate version multipart upload

Errors

Stable error shape

Automation clients should branch on the error code, not on human-facing copy.

{
  "error": "Item not found",
  "code": "item_not_found",
  "details": {}
}

Operations

Production behavior

The API records last-use metadata, writes audit logs best-effort, and keeps signed storage URLs short-lived.

OpenAPI

OpenAPI 3.1 document is served from /api/openapi/cli-v1
Use it for client generation, tests, and partner reviews

Downloads

items.view is checked before URL issuance
Unicode filenames use RFC 5987 content disposition

Repo docs

Deep implementation docs live under docs/API-CLI
Future clients, reports, and tracker sync should extend v1 additively