loopctl

https://loopctl.com/wiki
Admin
loopctl is a process integrity and chain-of-custody enforcement platform for AI agent development...
Tokens:7,113
Snippets:109
Trust Score:2.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install the MCP server

Source: https://loopctl.com/wiki/agent-bootstrap

Install the loopctl MCP server package via npm for integration with Claude Code.

```bash
npm install loopctl-mcp-server
```

--------------------------------

### Connect MCP Server

Source: https://loopctl.com

Install the MCP server and configure it in the .mcp.json file.

```json
npm install loopctl-mcp-server

// Add to .mcp.json
{
"mcpServers": {
  "loopctl": {
    "command": "npx",
    "args": ["loopctl-mcp-server"],
    "env": {
      "LOOPCTL_SERVER": "https://loopctl.com",
      "LOOPCTL_ORCH_KEY": "lc_your_orchestrator_key",
      "LOOPCTL_AGENT_KEY": "lc_your_agent_key"
    }
  }
}
}
```

--------------------------------

### POST /api/v1/stories/$ID/claim

Source: https://loopctl.com

Claims a story and starts the work process.

```APIDOC
## POST /api/v1/stories/$ID/claim

### Description
Claim and start work on a story.

### Method
POST

### Endpoint
https://loopctl.com/api/v1/stories/$ID/claim
```

--------------------------------

### GET /.well-known/loopctl

Source: https://loopctl.com/wiki/discovery

Fetches the discovery document containing service metadata, repository information, and relevant system URLs.

```APIDOC
## GET /.well-known/loopctl

### Description
Retrieves the discovery document for loopctl, providing agents with necessary configuration URLs and system metadata.

### Method
GET

### Endpoint
https://loopctl.com/.well-known/loopctl

### Response
#### Success Response (200)
- **spec_version** (string) - The version of the discovery specification.
- **mcp_server** (object) - Metadata about the MCP server including name, version, and repository URL.
- **audit_signing_key_url** (string) - URI template for the audit public key.
- **capability_scheme_url** (string) - URL for the capability tokens documentation.
- **chain_of_custody_spec_url** (string) - URL for the chain of custody specification.
- **discovery_bootstrap_url** (string) - URL for agent bootstrap instructions.
- **required_agent_pattern_url** (string) - URL for the required agent pattern documentation.
- **system_articles_endpoint** (string) - API endpoint for system articles.
- **contact** (string) - Contact email for the operator.
```

--------------------------------

### GET /api/v1/stories

Source: https://loopctl.com

Retrieves a list of stories associated with the project.

```APIDOC
## GET /api/v1/stories

### Description
List all stories for your project.

### Method
GET

### Endpoint
https://loopctl.com/api/v1/stories
```

--------------------------------

### GET /.well-known/loopctl/schema.json

Source: https://loopctl.com/wiki/discovery

Retrieves the JSON Schema for the discovery document.

```APIDOC
## GET /.well-known/loopctl/schema.json

### Description
Retrieves the JSON Schema used to validate the discovery document.

### Method
GET

### Endpoint
https://loopctl.com/.well-known/loopctl/schema.json
```

--------------------------------

### Create a Project

Source: https://loopctl.com

Initialize a new project using the API.

```bash
curl -X POST https://loopctl.com/api/v1/projects \
-H "Authorization: Bearer $YOUR_KEY" \
-d '{"name": "My App", "slug": "my-app"}'
```

--------------------------------

### Register Tenant Instructions

Source: https://loopctl.com

Instructions for tenant registration via the web portal.

```bash
# Visit https://loopctl.com/signup to create your tenant.
# Signup requires a hardware authenticator (YubiKey, Touch ID,
# or Windows Hello) — no API-based registration.
```

--------------------------------

### POST /stories/:id/start

Source: https://loopctl.com/wiki/agent-pattern

Signals that the implementation phase has begun.

```APIDOC
## POST /stories/:id/start

### Description
Signals that implementation has begun to transition from assigned to implementing.

### Method
POST

### Endpoint
/stories/:id/start

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the story.
```

--------------------------------

### Find ready stories

Source: https://loopctl.com/wiki/agent-bootstrap

Retrieve a list of stories currently marked as ready for a specific project.

```bash
curl -H "Authorization: Bearer lc_YOUR_KEY" \
  "https://loopctl.com/api/v1/projects/PROJECT_ID/stories/ready"
```

--------------------------------

### Manage Story Lifecycle via API

Source: https://loopctl.com

Use these commands to list projects, contract stories, and claim work. Requires a valid Authorization Bearer token.

```bash
# List stories for your project
$ curl -H "Authorization: Bearer $KEY" \
  https://loopctl.com/api/v1/stories

# Contract a story (commit to AC count)
$ curl -X POST \
  -H "Authorization: Bearer $KEY" \
  -d '{"story_title": "...", "ac_count": 12}' \
  https://loopctl.com/api/v1/stories/$ID/contract

# Claim and start work
$ curl -X POST \
  -H "Authorization: Bearer $KEY" \
  https://loopctl.com/api/v1/stories/$ID/claim
```

--------------------------------

### Discover the API

Source: https://loopctl.com/wiki/agent-bootstrap

Fetch the well-known discovery document to retrieve protocol version, MCP server details, and endpoint information.

```bash
curl https://loopctl.com/.well-known/loopctl
```

--------------------------------

### Contract and claim a story

Source: https://loopctl.com/wiki/agent-bootstrap

Acknowledge acceptance criteria for a story and then claim it to begin implementation.

```bash
# Contract
curl -X POST -H "Authorization: Bearer lc_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"story_title": "...", "ac_count": N}' \
  "https://loopctl.com/api/v1/stories/STORY_ID/contract"

# Claim
curl -X POST -H "Authorization: Bearer lc_YOUR_KEY" \
  "https://loopctl.com/api/v1/stories/STORY_ID/claim"
```

--------------------------------

### POST /stories/:id/request-review

Source: https://loopctl.com/wiki/agent-pattern

Notifies the reviewer that the implementation is ready for review.

```APIDOC
## POST /stories/:id/request-review

### Description
Fires a webhook to notify the reviewer that the implementation is ready.

### Method
POST

### Endpoint
/stories/:id/request-review

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the story.
```

--------------------------------

### Create API Keys for Agents

Source: https://loopctl.com

Generate API keys for orchestrator and agent roles using curl.

```bash
curl -X POST https://loopctl.com/api/v1/api_keys \
-H "Authorization: Bearer $YOUR_KEY" \
-d '{"name": "orchestrator", "role": "orchestrator"}'

curl -X POST https://loopctl.com/api/v1/api_keys \
-H "Authorization: Bearer $YOUR_KEY" \
-d '{"name": "agent", "role": "agent"}'
```

--------------------------------

### Create a dispatch via API

Source: https://loopctl.com/wiki/dispatch-lineage

Use this POST request to generate a new dispatch with an ephemeral key for a sub-agent. The response contains the raw_key required for sub-agent authentication.

```bash
curl -X POST https://loopctl.com/api/v1/dispatches \
  -H "Authorization: Bearer $ORCH_KEY" \
  -d '{"role": "agent", "agent_id": "...", "story_id": "...", "expires_in_seconds": 3600}'
```

--------------------------------

### Retrieve stories via API

Source: https://loopctl.com

Fetches a list of stories from the Loopctl API using an authorization token.

```bash
$ curl -s -H "Authorization: Bearer $KEY" \
  https://loopctl.com/api/v1/stories | jq

{
  "data": [
    {
      "id": "a3f1...",
      "title": "Landing page",
      "agent_status": "implementing",
      "verified_status": "unverified"
    }
  ]
}
```

--------------------------------

### Authenticate with Bearer Token

Source: https://loopctl.com/wiki/agent-bootstrap

Use the provided API key as a Bearer token in the Authorization header to access project resources.

```bash
curl -H "Authorization: Bearer lc_YOUR_KEY" \
  https://loopctl.com/api/v1/projects
```

--------------------------------

### Story State Machine Transitions

Source: https://loopctl.com/wiki/agent-pattern

Visual representation of the story lifecycle states and transition paths.

```text
pending → contracted → assigned → implementing → reported_done → verified
                                                    ↓
                                                 rejected → pending (retry)
```

--------------------------------

### POST /api/v1/dispatches

Source: https://loopctl.com/wiki/dispatch-lineage

Creates a new dispatch with an ephemeral API key for a sub-agent, scoped to a specific story and duration.

```APIDOC
## POST /api/v1/dispatches

### Description
Creates a new dispatch assignment for a sub-agent. The response includes an ephemeral `raw_key` which must be provided to the sub-agent.

### Method
POST

### Endpoint
https://loopctl.com/api/v1/dispatches

### Request Body
- **role** (string) - Required - The role of the agent (e.g., "agent")
- **agent_id** (string) - Required - The unique identifier for the agent
- **story_id** (string) - Required - The story identifier to scope the dispatch
- **expires_in_seconds** (integer) - Required - The TTL for the ephemeral key in seconds

### Request Example
{
  "role": "agent",
  "agent_id": "...",
  "story_id": "...",
  "expires_in_seconds": 3600
}

### Response
#### Success Response (200)
- **raw_key** (string) - The ephemeral API key for the sub-agent
```

--------------------------------

### Review acceptance criteria

Source: https://loopctl.com/wiki/verify-story

Fetches the acceptance criteria for a specific story using its ID.

```bash
curl -H "Authorization: Bearer $VERIFY_KEY" \
  "https://loopctl.com/api/v1/stories/STORY_ID/acceptance_criteria"
```

--------------------------------

### Report and Verify Story Completion

Source: https://loopctl.com

These commands handle the reporting of completed work and the final verification process. Note that reporting and verification must be performed by authorized reviewers or orchestrators, not the original implementer.

```bash
# Report story done (reviewer, not implementer)
$ curl -X POST \
  -H "Authorization: Bearer $REVIEWER_KEY" \
  https://loopctl.com/api/v1/stories/$ID/report

# Record review completion (with findings math)
$ curl -X POST \
  -H "Authorization: Bearer $REVIEWER_KEY" \
  -d '{"findings_count": 5, "fixes_count": 5}' \
  https://loopctl.com/api/v1/stories/$ID/review-complete

# Verify (orchestrator confirms)
$ curl -X POST \
  -H "Authorization: Bearer $ORCH_KEY" \
  https://loopctl.com/api/v1/stories/$ID/verify
```

--------------------------------

### Find stories awaiting verification

Source: https://loopctl.com/wiki/verify-story

Retrieves a list of stories with 'unverified' status and 'reported_done' agent status.

```bash
curl -H "Authorization: Bearer $VERIFY_KEY" \
  "https://loopctl.com/api/v1/stories?verified_status=unverified&agent_status=reported_done"
```

--------------------------------

### Submit verification

Source: https://loopctl.com/wiki/verify-story

Submits the verification result for a story, requiring a summary and the capability ID.

```bash
curl -X POST -H "Authorization: Bearer $VERIFY_KEY" \
  -d '{"summary": "All ACs verified", "cap_id": "..."}' \
  "https://loopctl.com/api/v1/stories/STORY_ID/verify"
```

--------------------------------

### Fetch Discovery Document

Source: https://loopctl.com/wiki/discovery

Retrieve the discovery document from the well-known URL. No authentication is required for this request.

```http
GET https://loopctl.com/.well-known/loopctl
```

--------------------------------

### Fetch Discovery Schema

Source: https://loopctl.com/wiki/discovery

Retrieve the JSON Schema used to validate the discovery document.

```http
GET https://loopctl.com/.well-known/loopctl/schema.json
```

--------------------------------

### Define a code pattern verification criterion

Source: https://loopctl.com/wiki/acceptance-criteria-bindings

Specifies a file path, line range, and regex pattern to verify existence in the codebase.

```json
{"type": "code", "path": "lib/my_module.ex", "line_range": [10, 50], "pattern": "def create"}
```

--------------------------------

### POST /stories/:id/contract

Source: https://loopctl.com/wiki/agent-pattern

Signals that the agent has read the acceptance criteria and understands the requirements.

```APIDOC
## POST /stories/:id/contract

### Description
Signals understanding of the story's acceptance criteria to transition from pending to contracted.

### Method
POST

### Endpoint
/stories/:id/contract

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the story.
```

--------------------------------

### POST /stories/:id/verify

Source: https://loopctl.com/wiki/agent-pattern

Verifies the completed story by an agent other than the implementer.

```APIDOC
## POST /stories/:id/verify

### Description
Verifies the story to transition from reported_done to verified. Returns 409 self_verify_blocked if the caller is the implementer.

### Method
POST

### Endpoint
/stories/:id/verify

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the story.
```

--------------------------------

### Clear a custody halt via API

Source: https://loopctl.com/wiki/break-glass

Endpoint to clear a tenant halt. Requires a fresh WebAuthn assertion from a root authenticator.

```http
POST /api/v1/admin/tenants/:id/clear-halt
```

--------------------------------

### Define a test verification criterion

Source: https://loopctl.com/wiki/acceptance-criteria-bindings

Specifies a test file and name for the runner to execute and verify.

```json
{"type": "test", "path": "test/my_module_test.exs", "test_name": "creates a record"}
```

--------------------------------

### Define a migration verification criterion

Source: https://loopctl.com/wiki/acceptance-criteria-bindings

Checks for the existence of a specific column within a database table.

```json
{"type": "migration", "table": "dispatches", "column": "lineage_path"}
```

--------------------------------

### Discovery Response Schema

Source: https://loopctl.com/wiki/discovery

The JSON structure returned by the discovery endpoint, containing system metadata and configuration URLs.

```json
{
  "spec_version": "2",
  "mcp_server": {
    "name": "loopctl-mcp-server",
    "npm_version": "2.0.0",
    "repository_url": "https://github.com/mkreyman/loopctl/..."
  },
  "audit_signing_key_url": "https://loopctl.com/api/v1/tenants/{tenant_id}/audit_public_key",
  "capability_scheme_url": "https://loopctl.com/wiki/capability-tokens",
  "chain_of_custody_spec_url": "https://loopctl.com/wiki/chain-of-custody",
  "discovery_bootstrap_url": "https://loopctl.com/wiki/agent-bootstrap",
  "required_agent_pattern_url": "https://loopctl.com/wiki/agent-pattern",
  "system_articles_endpoint": "https://loopctl.com/api/v1/articles/system",
  "contact": "operator@loopctl.com"
}
```

--------------------------------

### Define a route verification criterion

Source: https://loopctl.com/wiki/acceptance-criteria-bindings

Verifies that a specific HTTP method and path exist in the application router.

```json
{"type": "route", "method": "POST", "path": "/api/v1/stories/:id/verify"}
```

--------------------------------

### POST /api/v1/stories/$ID/contract

Source: https://loopctl.com

Contracts a story by committing to an acceptance criteria count.

```APIDOC
## POST /api/v1/stories/$ID/contract

### Description
Contract a story by committing to the AC count.

### Method
POST

### Endpoint
https://loopctl.com/api/v1/stories/$ID/contract

### Request Body
- **story_title** (string) - Required - The title of the story
- **ac_count** (integer) - Required - The number of acceptance criteria
```

--------------------------------

### POST /api/v1/stories/$ID/verify

Source: https://loopctl.com

Confirms verification of a story by the orchestrator.

```APIDOC
## POST /api/v1/stories/$ID/verify

### Description
Verify (orchestrator confirms).

### Method
POST

### Endpoint
https://loopctl.com/api/v1/stories/$ID/verify
```

--------------------------------

### Define a manual verification criterion

Source: https://loopctl.com/wiki/acceptance-criteria-bindings

Requires human intervention and approval via the manual review dashboard.

```json
{"type": "manual", "description": "Operator must visually inspect the UI"}
```

--------------------------------

### POST /api/v1/stories/$ID/review-complete

Source: https://loopctl.com

Records the completion of a review with findings and fixes counts.

```APIDOC
## POST /api/v1/stories/$ID/review-complete

### Description
Record review completion with findings and fixes counts.

### Method
POST

### Endpoint
https://loopctl.com/api/v1/stories/$ID/review-complete

### Request Body
- **findings_count** (integer) - Required - Number of findings
- **fixes_count** (integer) - Required - Number of fixes
```

--------------------------------

### POST /api/v1/stories/$ID/report

Source: https://loopctl.com

Reports a story as done, performed by a reviewer.

```APIDOC
## POST /api/v1/stories/$ID/report

### Description
Report story done (reviewer, not implementer).

### Method
POST

### Endpoint
https://loopctl.com/api/v1/stories/$ID/report
```

--------------------------------

### POST /api/v1/admin/tenants/:id/clear-halt

Source: https://loopctl.com/wiki/break-glass

Clears a custody halt for a specific tenant. This operation requires a fresh WebAuthn assertion from a root authenticator.

```APIDOC
## POST /api/v1/admin/tenants/:id/clear-halt

### Description
Clears a custody halt for a tenant. This is an emergency procedure used when a tenant is halted due to a false-positive divergence detection, lost authenticators, or a corrupted audit chain.

### Method
POST

### Endpoint
/api/v1/admin/tenants/:id/clear-halt

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the tenant.
```

--------------------------------

### Six-Layer Enforcement Stack

Source: https://loopctl.com/wiki/chain-of-custody

The architectural layers used by loopctl to ensure system integrity and prevent agent manipulation.

```text
L0  Human + hardware anchor (WebAuthn at signup)
L1  Capability tokens (signed, scoped, non-replayable)
L2  Database invariants (FK, CHECK, triggers, partial indexes)
L3  Independent re-execution (SWE-bench-style verification)
L4  Structural role separation (dispatch lineage, rotating verifier)
L5  Behavioral detection (lazy-bastard score, CoT sanity monitor)
L6  Halt on byzantine conditions (divergent STH, custody halt)
```

--------------------------------

### POST /stories/:id/claim

Source: https://loopctl.com/wiki/agent-pattern

Locks the story to the agent to prevent double-claims.

```APIDOC
## POST /stories/:id/claim

### Description
Locks the story to the agent using pessimistic locking to transition from contracted to assigned.

### Method
POST

### Endpoint
/stories/:id/claim

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the story.
```

--------------------------------

### POST /stories/:id/report

Source: https://loopctl.com/wiki/agent-pattern

Reports the story as done by an agent other than the implementer.

```APIDOC
## POST /stories/:id/report

### Description
Reports the story as done to transition from implementing to reported_done. Returns 409 self_report_blocked if the caller is the implementer.

### Method
POST

### Endpoint
/stories/:id/report

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the story.
```
Tokens:
Raw