# Endpoints

Documentation of the DeployAlly REST API endpoints. Base URL: https://sys.deployally.com/api/v1.

All endpoints require authentication via Authorization: Bearer da_xxx header (see Authentication).

# Templates

# GET /templates

List templates published in the catalog.

Query Parameters:

curl -X GET "https://sys.deployally.com/api/v1/templates" \
  -H "Authorization: Bearer da_xxx"

Response (200):

{
  "success": true,
  "data": [
    {
      "id": "tpl_memos",
      "species": "memos",
      "archetype": "application",
      "version": "0.20",
      "taxonomy": {
        "kingdom": "applications",
        "family": "productivity",
        "species": "memos"
      },
      "spec_hash": "sha256:abc123...",
      "status": "published"
    }
  ]
}

# GET /templates/featured

List featured templates.

curl -X GET "https://sys.deployally.com/api/v1/templates/featured" \
  -H "Authorization: Bearer da_xxx"

# GET /templates/upcoming

List templates in development (preview).

curl -X GET "https://sys.deployally.com/api/v1/templates/upcoming" \
  -H "Authorization: Bearer da_xxx"

# GET /templates/{species}

Return the full template (spec) by species.

Cache: Cache-Control: max-age=60. To force refresh, add a unique query string (?_=$(date +%s)).

curl -X GET "https://sys.deployally.com/api/v1/templates/memos" \
  -H "Authorization: Bearer da_xxx"

Response:

{
  "success": true,
  "data": {
    "id": "tpl_memos",
    "species": "memos",
    "archetype": "application",
    "version": "0.20",
    "spec": {
      "image": "neosmemo/memos:0.20",
      "inputs": { "required": [...], "optional": [...] },
      "secrets": {...},
      "routes": [...],
      "healthcheck": {...},
      "storage": [...]
    },
    "spec_hash": "sha256:abc123..."
  }
}

# Taxonomy

# GET /taxonomy/tree

Return the full taxonomic tree (kingdom → family → species).

curl -X GET "https://sys.deployally.com/api/v1/taxonomy/tree" \
  -H "Authorization: Bearer da_xxx"

# GET /taxonomy/kingdoms

List all kingdoms.

# GET /taxonomy/kingdoms/{kingdom_id}

Details of a kingdom.

# GET /taxonomy/families/{family_id}

Details of a family.

# GET /taxonomy/species/{species_id}

Details of a species.

# Definitions

Definitions are template + parameters + instance metadata, saved for deploy.

# GET /definitions

List definitions of the user/server.

curl -X GET "https://sys.deployally.com/api/v1/definitions" \
  -H "Authorization: Bearer da_xxx"

# POST /definitions

Create a new definition.

Request Body:

curl -X POST "https://sys.deployally.com/api/v1/definitions" \
  -H "Authorization: Bearer da_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "species": "memos",
    "instance_uid": "memos-001",
    "server_id": "srv_123",
    "inputs": {
      "WEB_HOSTNAME": "memos.example.com"
    },
    "profile": "production"
  }'

# GET /definitions/{id}

Details of a definition.

# PUT /definitions/{id}

Update a definition (creates a new revision).

# DELETE /definitions/{id}

Archive a definition (soft delete).

# POST /definitions/{id}/activate

Reactivate an archived definition.

# GET /definitions/{id}/revisions

List the definition's revisions.

# POST /definitions/{id}/revisions/{number}/restore

Restore a previous revision as the active one.

# Instances

Instances represent running containers.

# GET /instances

List instances.

curl -X GET "https://sys.deployally.com/api/v1/instances" \
  -H "Authorization: Bearer da_xxx"

# GET /instances/stats

Aggregated instance statistics (running, failures, etc).

# GET /instances/{id}

Details of an instance.

# POST /instances/report

Endpoint used by the CLI/daemon to report container status on the server.

# POST /instances/components/sync

Sync components (individual containers of multi-component templates).

# POST /instances/{id}/drift

Report drift (difference between declared state and real state).

# GET /instances/{id}/deployments

Deployment history of the instance.

# POST /instances/{id}/release

Release instance resources (stop containers, optionally remove volumes).

# Actions

Actions are post-deploy operations declared in the template (e.g., dump-database, clear-cache, create-database).

# GET /instances/{id}/actions

List actions available for the instance + backup metadata.

curl -X GET "https://sys.deployally.com/api/v1/instances/inst_abc/actions" \
  -H "Authorization: Bearer da_xxx"

Response:

{
  "success": true,
  "template_species": "mysql",
  "actions": [
    {
      "name": "Dump Database",
      "slug": "dump-database",
      "description": "Export full database dump",
      "type": "exec",
      "timeout": "300s",
      "dangerous": false,
      "params": [
        {
          "name": "databases",
          "type": "string",
          "required": false,
          "default": "--all-databases"
        }
      ]
    }
  ],
  "backup": {
    "strategy": "both",
    "volumes": [{"name": "mysql_data", "critical": true}],
    "dump_action": "dump-database",
    "schedule_hint": "daily"
  }
}

# POST /instances/{id}/actions/{slug}/execute

Trigger action execution. Returns 202 Accepted with the execution ID.

curl -X POST "https://sys.deployally.com/api/v1/instances/inst_abc/actions/create-database/execute" \
  -H "Authorization: Bearer da_xxx" \
  -H "Content-Type: application/json" \
  -d '{"params": {"db_name": "blog"}}'

# GET /actions/{execution_id}

Check the status of an execution.

Possible statuses: pending, sent, running, completed, failed, timeout, cancelled

# PUT /actions/{execution_id}

Update an execution's status (used by the daemon to report result).

# GET /instances/{id}/actions/history

Execution history of an instance.

# Playbooks

# GET /playbooks

List available playbook types.

# GET /playbooks/{playbook_type}

Details of a playbook type.

# Servers

# GET /servers

List registered servers.

# POST /servers/register

Register a new server.

curl -X POST "https://sys.deployally.com/api/v1/servers/register" \
  -H "Authorization: Bearer da_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-server-01",
    "environment": "production"
  }'

Important: The server's returned api_key is shown only once. Store it securely.

# GET /servers/{id}

Details of a server.

# PUT /servers/{id}

Update a server.

# POST /servers/{id}/rotate-key

Rotate the server's API key.

# Server Capacity

# GET /server-capacity

List capacity of all servers.

# GET /server-capacity/{server_id}

Capacity of a server (memory used/free, CPU, disk).

# PUT /server-capacity/{server_id}

Update capacity info (used by the daemon).

# Deployments

# GET /deployments

List deployment history.

# POST /deployments/execute

Trigger a deployment.

curl -X POST "https://sys.deployally.com/api/v1/deployments/execute" \
  -H "Authorization: Bearer da_xxx" \
  -H "Content-Type: application/json" \
  -d '{"definition_id": "def_xyz789"}'

# GET /deployments/pending

List deployments pending execution.

# GET /deployments/{id}

Details of a deployment, including logs.

# PATCH /deployments/{id}/status

Update deployment status (used by the daemon).

# POST /deployments/{id}/rollback

Roll back a deployment.

# Manifests

Manifests represent the resolved spec (after Reflang) of an instance.

# GET /manifest

Return the manifest of the requested instance (used by the CLI during deploy).

# POST /deploy/report

Report deploy result (executed by the daemon).

# Secrets

# GET /definitions/{id}/secrets (via secrets bp)

List secrets associated with a definition (no values).

# Vault endpoints (`/vault`)

Internal endpoints for encrypted secrets management.

# Match

# POST /match

Find templates compatible with resolving a declared needs.

curl -X POST "https://sys.deployally.com/api/v1/match" \
  -H "Authorization: Bearer da_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "needs": [{"class": "mysql"}]
  }'

# Tenants

# GET /tenants

List user tenants.

# POST /tenants

Create a new tenant.

# GET /tenants/{id}

Tenant details.

# PATCH /tenants/{id}/suspend

Suspend tenant.

# PATCH /tenants/{id}/resume

Resume a suspended tenant.

# PATCH /tenants/{id}/active

Mark tenant as active.

# POST /tenants/{id}/migrate

Migrate tenant between servers.

# DELETE /tenants/{id}

Remove tenant.

# Webhooks

# GET /webhooks/endpoints

List configured webhook endpoints.

# POST /webhooks/endpoints

Create a new endpoint.

curl -X POST "https://sys.deployally.com/api/v1/webhooks/endpoints" \
  -H "Authorization: Bearer da_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://my-site.com/webhook",
    "events": ["deployment.success", "instance.unhealthy"],
    "secret": "my_webhook_secret"
  }'

# DELETE /webhooks/endpoints/{id}

Remove endpoint.

# GET /events

List triggered events (audit log).

Available events:

• deployment.started
• deployment.success
• deployment.failed
• instance.started
• instance.stopped
• instance.unhealthy
• definition.created
• definition.updated
• action.completed
• action.failed

# Recipes

Recipes are community-collaborative templates (not part of the curated catalog).

# GET /recipes

List public recipes.

# GET /recipes/by-slug/{slug}

Recipe details by slug.

# GET /recipes/mine

List the user's recipes.

# POST /recipes

Submit a new recipe for review.

# PATCH /recipes/{id}

Update a recipe.

# POST /recipes/{id}/upvote

Vote on a recipe.

# PATCH /recipes/{id}/withdraw

Withdraw a submitted recipe.

# DELETE /recipes/{id}

Remove a recipe.

# GET /recipes/pending

List recipes pending review (admin).

# POST /recipes/{id}/approve

Approve recipe (admin).

# POST /recipes/{id}/reject

Reject recipe (admin).

# Saved Configs

# GET /saved-configs

List the user's saved configurations.

# POST /saved-configs

Create a new saved config.

# GET /saved-configs/{id}

Config details.

# PATCH /saved-configs/{id}

Update config.

# DELETE /saved-configs/{id}

Remove config.

# Upgrades

# GET /upgrades

List upgrades available for active instances.

# POST /upgrades/scan

Trigger a scan for new versions.

# POST /upgrades/{id}/ack

Mark upgrade as acknowledged (without applying).

# POST /upgrades/{id}/apply

Apply the upgrade.

# Copilot

# POST /copilot/ask

Ask the Copilot (LLM with catalog context).

# GET /copilot/usage

User's Copilot consumption.

# User

# GET /user/servers

List servers of the authenticated user.

# Implant

Endpoints for downloading the Implant agent (server prep).

# GET /implant/{os_type}/{arch}

Return metadata of the Implant binary.

# GET /implant/{os_type}/{arch}/download

Download the Implant binary.

# Health Check

# GET /health

Verify the API is up (no authentication required).

curl -X GET "https://sys.deployally.com/api/v1/health"

Response:

{
  "status": "healthy",
  "timestamp": "2026-06-05T12:00:00Z"
}

# WebSocket

# WS /ws/server

WebSocket endpoint for the daemon's persistent connection (receives remote actions).

Protocol:

# Standard Responses

# Success

{ "success": true, "data": { ... } }

# Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'name' is required"
  }
}

# Error Codes

# Rate Limits

Response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1699900000

# Next Steps

• Authentication — API key management
• API Integration — practical guide
• CLI Reference — programmatic use via CLI