Project Provisioning API

Server-to-server endpoint that lets an external automation create a new Punchline project without a human clicking through the web UI, and receive a fresh project-scoped API key in the same response — ready to use immediately for creating tickets, etc.

Overview

Direction: server-to-server only. Do not call from a browser.
Auth: a user-level API key (pnchl_user_...) in the same X-Punchline-Key header used by project keys.
Provisioning-only: a user-level key works only on this endpoint. Used on any other external endpoint (tickets, changelog, etc.) it returns 403. A project-scoped key (pnchl_live_...) used on this endpoint also returns 403 — project keys can't provision.
Ownership: the caller (the key's owner) becomes the new project's OWNER.

Getting a user-level key

Create one from your Punchline Settings page (/settings) → API Keys. Give it a name (e.g. "CI provisioning key"); the plaintext (pnchl_user_...) is shown exactly once — store it as a secret. Revoke it from the same page.

Endpoint

POST /api/v1/external/projects
Content-Type: application/json
X-Punchline-Key: <your user-level key>

Request body

Field	Type	Required	Notes
`name`	string (≤ 255 chars)	yes	Display name.
`slug`	string	yes	Lowercase letters, digits, hyphens, 2–100 chars (`^[a-z0-9-]{2,100}$`). Must be unique.
`prefix`	string	yes	2–10 uppercase letters (`^[A-Z]{2,10}$`), used for ticket display IDs (e.g. `ACME-148`). Must be unique.
`description`	string	no	Free text.

Validation matches internal project creation (POST /api/v1/projects).

Responses

Status	Body
201	`{ "slug", "name", "prefix", "apiKey" }`
400	RFC 7807 ProblemDetail (validation error)
401	RFC 7807 ProblemDetail (missing, invalid, or revoked key)
403	RFC 7807 ProblemDetail — a project-scoped key was used here, or a user key was used on any other external endpoint
409	RFC 7807 ProblemDetail — `slug` or `prefix` already taken

apiKey is a brand-new project-scoped key (pnchl_live_...) for the just-created project, shown once, in this response only — it cannot be retrieved again. Use it right away to operate on the new project, e.g. via the External Ticket Creation API.

Sample: cURL

curl -X POST https://punchline.example.com/api/v1/external/projects \
  -H "X-Punchline-Key: pnchl_user_a1B2c3D4e5F6g7H8i9J0kLmNoPqRsTuVwXy" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Widgets",
    "slug": "acme-widgets",
    "prefix": "ACME",
    "description": "Provisioned via CI"
  }'

Response:

{
  "slug": "acme-widgets",
  "name": "Acme Widgets",
  "prefix": "ACME",
  "apiKey": "pnchl_live_kza3..."
}

Errors

Status	When	Action
401	Missing, malformed, unknown, or revoked key	Confirm the key, or issue a new one from Settings
403	Used a project-scoped (`pnchl_live_`) key here, or a user-level key on a different external endpoint	Use a user-level key here, and its returned project key everywhere else
409	`slug` or `prefix` already in use by another project	Choose a different slug/prefix
400	Body validation failed	Inspect the ProblemDetail's `detail` field

External Ticket Creation & Follow-Up — use the apiKey returned here to create, read, and update tickets in the new project.