attune/docs/QUICKREF-pack-management-api.md

Quick Reference: Pack Management API

Last Updated: 2026-02-05

Overview

Four API endpoints for pack installation workflow:

1. Download - Fetch packs from sources
2. Dependencies - Analyze requirements
3. Build Envs - Prepare runtimes (detection mode)
4. Register - Import to database

All endpoints require Bearer token authentication.

---

1. Download Packs

POST /api/v1/packs/download

Minimal Request:

{
  "packs": ["core"],
  "destination_dir": "/tmp/packs"
}

Full Request:

{
  "packs": ["core", "github:attune-io/pack-aws@v1.0.0"],
  "destination_dir": "/tmp/packs",
  "registry_url": "https://registry.attune.io/index.json",
  "ref_spec": "main",
  "timeout": 300,
  "verify_ssl": true
}

Response:

{
  "data": {
    "downloaded_packs": [...],
    "failed_packs": [...],
    "total_count": 2,
    "success_count": 1,
    "failure_count": 1
  }
}

cURL Example:

curl -X POST http://localhost:8080/api/v1/packs/download \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"packs":["core"],"destination_dir":"/tmp/packs"}'

---

2. Get Dependencies

POST /api/v1/packs/dependencies

Request:

{
  "pack_paths": ["/tmp/packs/core"],
  "skip_validation": false
}

Response:

{
  "data": {
    "dependencies": [...],
    "runtime_requirements": {...},
    "missing_dependencies": [...],
    "analyzed_packs": [...],
    "errors": []
  }
}

cURL Example:

curl -X POST http://localhost:8080/api/v1/packs/dependencies \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pack_paths":["/tmp/packs/core"]}'

---

3. Build Environments

POST /api/v1/packs/build-envs

Minimal Request:

{
  "pack_paths": ["/tmp/packs/aws"],
  "packs_base_dir": "/opt/attune/packs"
}

Full Request:

{
  "pack_paths": ["/tmp/packs/aws"],
  "packs_base_dir": "/opt/attune/packs",
  "python_version": "3.11",
  "nodejs_version": "20",
  "skip_python": false,
  "skip_nodejs": false,
  "force_rebuild": false,
  "timeout": 600
}

Response:

{
  "data": {
    "built_environments": [...],
    "failed_environments": [...],
    "summary": {
      "total_packs": 1,
      "success_count": 1,
      "python_envs_built": 1,
      "nodejs_envs_built": 0
    }
  }
}

Note: Currently in detection mode - checks runtime availability but doesn't build full environments.

cURL Example:

curl -X POST http://localhost:8080/api/v1/packs/build-envs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pack_paths":["/tmp/packs/core"],"packs_base_dir":"/opt/attune/packs"}'

---

4. Register Packs (Batch)

POST /api/v1/packs/register-batch

Minimal Request:

{
  "pack_paths": ["/opt/attune/packs/core"],
  "packs_base_dir": "/opt/attune/packs"
}

Full Request:

{
  "pack_paths": ["/opt/attune/packs/core"],
  "packs_base_dir": "/opt/attune/packs",
  "skip_validation": false,
  "skip_tests": false,
  "force": false
}

Response:

{
  "data": {
    "registered_packs": [...],
    "failed_packs": [...],
    "summary": {
      "total_packs": 1,
      "success_count": 1,
      "failure_count": 0,
      "total_components": 46,
      "duration_ms": 1500
    }
  }
}

cURL Example:

curl -X POST http://localhost:8080/api/v1/packs/register-batch \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pack_paths":["/opt/attune/packs/core"],"packs_base_dir":"/opt/attune/packs","skip_tests":true}'

---

Action Wrappers

Execute via CLI or workflows:

# Download
attune action execute core.download_packs \
  --param packs='["core"]' \
  --param destination_dir=/tmp/packs

# Analyze dependencies
attune action execute core.get_pack_dependencies \
  --param pack_paths='["/tmp/packs/core"]'

# Build environments
attune action execute core.build_pack_envs \
  --param pack_paths='["/tmp/packs/core"]'

# Register
attune action execute core.register_packs \
  --param pack_paths='["/opt/attune/packs/core"]' \
  --param skip_tests=true

---

Complete Workflow Example

#!/bin/bash
TOKEN=$(attune auth token)

# 1. Download
DOWNLOAD=$(curl -s -X POST http://localhost:8080/api/v1/packs/download \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"packs":["aws"],"destination_dir":"/tmp/packs"}')

PACK_PATH=$(echo "$DOWNLOAD" | jq -r '.data.downloaded_packs[0].pack_path')

# 2. Check dependencies
curl -X POST http://localhost:8080/api/v1/packs/dependencies \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"pack_paths\":[\"$PACK_PATH\"]}"

# 3. Build/check environments
curl -X POST http://localhost:8080/api/v1/packs/build-envs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"pack_paths\":[\"$PACK_PATH\"]}"

# 4. Register
curl -X POST http://localhost:8080/api/v1/packs/register-batch \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"pack_paths\":[\"$PACK_PATH\"],\"skip_tests\":true}"

---

Common Parameters

Source Formats (download)

• Registry name: "core", "aws"
• Git URL: "https://github.com/org/repo.git"
• Git shorthand: "github:org/repo@tag"
• Local path: "/path/to/pack"

Auth Token

# Get token via CLI
TOKEN=$(attune auth token)

# Or login directly
LOGIN=$(curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"pass"}')
TOKEN=$(echo "$LOGIN" | jq -r '.data.access_token')

---

Error Handling

All endpoints return 200 with per-pack results:

{
  "data": {
    "successful_items": [...],
    "failed_items": [
      {
        "pack_ref": "unknown",
        "error": "pack.yaml not found"
      }
    ]
  }
}

Check success_count vs failure_count in summary.

---

Best Practices

1. Check authentication first - Verify token works
2. Process downloads - Check downloaded_packs array
3. Validate dependencies - Ensure missing_dependencies is empty
4. Skip tests in dev - Use skip_tests: true for faster iteration
5. Use force carefully - Only re-register when needed

---

Testing Quick Start

# 1. Start API
make run-api

# 2. Get token
TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@attune.local","password":"TestPass123!"}' \
  | jq -r '.data.access_token')

# 3. Test endpoint
curl -X POST http://localhost:8080/api/v1/packs/dependencies \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pack_paths":[]}' | jq

---

Related Docs

• Full API Docs: api-pack-installation.md
• Pack Structure: pack-structure.md
• Registry Spec: pack-registry-spec.md
• CLI Guide: cli.md