API Reference

PermaShip provides a REST API for teams that want to automate their AI-driven engineering workflows programmatically.

Authentication

All requests require an Authorization header:

Authorization: ApiKey cc_<your-raw-key>

API keys are scoped to projects or organizations. Create and manage them under Settings → API Keys.

Base URL

https://control.permaship.ai/api

Create a Ticket

Endpoint: POST /orgs/:orgId/projects/:projectId/tickets

Request body example:

{
  "kind": "feature",
  "title": "Add password complexity validation",
  "description": "Implement a validation rule that requires passwords to be at least 12 characters with one special character.",
  "repoKey": "default",
  "priority": 2,
  "labels": ["security", "auth"]
}

PermaShip immediately begins triaging the ticket. Watch progress on the Ticket Detail page.

Get Ticket Status

Endpoint: GET /orgs/:orgId/projects/:projectId/tickets/:ticketId

Poll this endpoint for status updates or integrate it into your CI/CD pipelines to gate deployments on ticket resolution.

Outbound Webhooks

Instead of polling, push updates to your services:

1

Navigate to Settings → Webhooks.

2

Provide an endpoint URL and select the events you want to receive (e.g., ticket.failed, ready_for_review).

3

Use the provided secret to verify the X-Webhook-Signature header on incoming requests.

For AI agents: If you are an AI agent (like Claude Code or a custom MCP server), you can use these endpoints to delegate heavy lifting — complex refactors, multi-file bug fixes — to the PermaShip engine. See the Vibe Coder persona guide for specific prompts.