API & MCP

REST API

Mint an API key under Settings → API keys — keys carry a role (admin / deployer / viewer), an environment scope, and secret visibility, enforced server-side. Authenticate with Authorization: Bearer yakd_….

GET  /api/v1/projects
POST /api/v1/projects
GET  /api/v1/projects/:id
POST /api/v1/projects/:id/environments
POST /api/v1/projects/:id/steps
POST /api/v1/projects/:id/releases      # cut a release (commit_sha, source_dirty, source_diff_sha256)
GET  /api/v1/deployments                # newest first; ?limit=&before_id=&project_id=&environment_id=&state=
POST /api/v1/deployments                # deploy a release
GET  /api/v1/deployments/:id
GET  /api/v1/deployments/:id/logs       # paged by seq: ?tail=N | ?after_seq= | ?order=desc&before_seq=
                                        #   &limit= (≤ 5000) &step_run_id= &stream= &q=
GET  /api/v1/deployments/:id/status     # state, steps, runner, last error, log tail
GET  /api/v1/deployments/:id/events     # Server-Sent Events until a terminal state
POST /api/v1/sites/:project/env         # change service env keys and restart (no artifact)
POST /api/v1/sites/:project/env/rollback
GET  /api/v1/sites/:project/releases    # paged; which release is live
GET  /api/v1/sites/:project/releases/:release_id/download   # presigned GET, 10 min
GET  /api/v1/sites/:project/service/current
GET  /api/v1/sites/:project/service/status
GET  /api/v1/sites/:project/service/logs?lines=200          # redacted, ≤ 2000
POST /api/v1/sites/:project/service/restart                 # approval-gated in production
POST /api/v1/sites/:project/service/rollback                # release_id optional

A minimal CI integration is two calls: cut a release, then deploy it and follow GET /api/v1/deployments/:id/events (or poll /status) until it reaches a terminal state. The stream sends status, log (redacted) and a final end event; reconnect with Last-Event-ID to resume without repeating log lines.

To read a finished run's log, start at the end: GET /api/v1/deployments/:id/logs?tail=500 returns the last 500 lines oldest first; pass its prev_before_seq as before_seq (with tail or order=desc) to page back, or a next_after_seq as after_seq to page forward. has_more says whether another page exists in that direction and total counts the matching lines. Narrow with stream=stderr, step_run_id or a substring q.

Report where a release's code came from with commit_sha, source_dirty and an optional source_diff_sha256; a project with Require a clean source tree refuses releases built from a dirty tree.

MCP (AI agents)

YakDeploy speaks the Model Context Protocol natively, so Claude, Cursor, and other MCP clients can list projects, cut releases, deploy, and read logs — with the same RBAC as everyone else (OAuth 2.1; the token carries role + environment scope). Settings → MCP apps has the connect URL and per-client instructions. Tools: list_projects · get_project · create_project · add_environment · add_step · cut_release · deploy · deployment_status · deployment_logs · list_deployments · whats_deployed · preview_variables · list_runbooks · run_runbook · rollback · search_logs · get_audit_events · explain_failure · site_env_update · site_env_rollback — an agent can diagnose a failed deploy in one explain_failure call and act on it.