# Spindle

> XRPC methods served by a spindle.

Served by `spindle` at `https://<spindle host>/xrpc/<method>`.

## org.tangled.ci.approvePipeline

`POST`. Approve blocked pipeline.

Input:

* `repo` (string, did, required): git repository DID
* `pipeline` (string, record-key, required): pipeline id

Errors:

* `PipelineNotFound`: Pipeline not found
* `PipelineNotBlocked`: Pipeline has no workflow waiting for approval

## org.tangled.ci.getWorkflowDefinition

`GET`.

Params:

* `repo` (string, did, required)
* `workflow` (string, required)

Output:

* `workflow` (`org.tangled.ci.workflow`, required)

Errors:

* `InvalidRequest`: Invalid request parameters
* `RepoNotFound`: Repository not found
* `WorkflowNotFound`: Workflow not found

## org.tangled.ci.listWorkflowDefinitions

`GET`.

Params:

* `repo` (string, did, required)
* `ref` (string, default `"HEAD"`)

Output:

* `workflows` (array of `org.tangled.ci.workflow`, required)

Errors:

* `InvalidRequest`: Invalid request parameters
* `RepoNotFound`: Repository not found
* `RefNotFound`: No branch or tag of the repository has this name

## org.tangled.ci.retryPipeline

`POST`. Duplicate existing pipeline for rerun.

Input:

* `repo` (string, did, required): git repository DID
* `pipeline` (string, record-key, required): pipeline id
* `workflows` (array of string): Workflow names to filter. When not provided, entire pipeline will be duplicated.

Output:

* `pipeline` (string, record-key, required): Scheduled pipeline id

Errors:

* `PipelineNotFound`: Pipeline not found
* `PipelineNotRetryable`: Pipeline is still blocked or has no stored spec to rerun

## org.tangled.event.notifyEvent

`POST`. notify an event from external source

Input:

* `repo` (string, did, required): Repository DID
* `event` (`org.tangled.ci.trigger.manual` or `org.tangled.event.push`, required): Tangled event object

Output:

* `pipeline` (string): Spindle-local id of the scheduled pipeline
* `message` (string): Text returned by the server for this push, like how to follow a started CI.

Errors:

* `InvalidRequest`: Invalid request parameters

## org.tangled.secret.addSecret

`POST`. Add a CI secret

Input:

* `repo` (string, did, required)
* `key` (string, required)
* `value` (string, required)

Errors:

* `InvalidRequest`: Invalid request parameters
* `RepoNotFound`: Repository not found
* `SecretAlreadyExists`: A secret with this key already exists.

## org.tangled.secret.listSecrets

`GET`.

Params:

* `repo` (string, did, required)

Output:

* `secrets` (array of `secret`, required)

Errors:

* `InvalidRequest`: Invalid request parameters
* `RepoNotFound`: Repository not found

## org.tangled.secret.removeSecret

`POST`. Remove a CI secret

Input:

* `repo` (string, did, required)
* `key` (string, required)

Errors:

* `InvalidRequest`: Invalid request parameters
* `RepoNotFound`: Repository not found
* `SecretNotFound`: The requested secret does not exist.

## org.tangled.webhook.createWebhook

`POST`. Create a new webhook for a repository.

Input:

* `repo` (string, did, required): DID of the repository as minted by the knot.
* `url` (string, uri, required): Endpoint URL that will receive webhook payloads.
* `active` (boolean, default `true`): Whether the webhook should be active immediately.
* `events` (array of `org.tangled.webhook.defs#eventType`, required): Event types to subscribe to.
* `secret` (string): Optional HMAC secret used to sign payloads. If omitted, payloads are not signed.

Output:

* `id` (string, required): ID of the newly created webhook.

Errors:

* `NoEventsSelected`: At least one event type must be specified.

## org.tangled.webhook.deleteWebhook

`POST`. Delete a webhook from a repository.

Input:

* `repo` (string, did, required): DID of the repository as minted by the knot.
* `webhook` (string, required): Webhook ID to delete.

Errors:

* `WebhookNotFound`

## org.tangled.webhook.listWebhookDeliveries

`GET`. List recent delivery attempts for a webhook.

Params:

* `repo` (string, did, required): DID of the repository as minted by the knot.
* `webhooks` (array of string, required)
* `limit` (integer, default `50`, 1 to 100)

Output:

* `deliveries` (array of `org.tangled.webhook.defs#delivery`, required)

## org.tangled.webhook.listWebhooks

`GET`. List webhooks configured for a repository.

Params:

* `repo` (string, did, required): DID of the repository as minted by the knot.

Output:

* `webhooks` (array of `org.tangled.webhook.defs#webhook`, required)

## org.tangled.webhook.retryWebhookDelivery

`POST`. Re-send a specific webhook delivery.

Input:

* `repo` (string, did, required): DID of the repository as minted by the knot.
* `webhook` (string, required): Webhook ID that owns the delivery.
* `delivery` (string, required): Delivery ID to retry.

Errors:

* `WebhookNotFound`
* `DeliveryNotFound`

## org.tangled.webhook.updateWebhook

`POST`. Update an existing webhook. Only supplied fields are changed.

Input:

* `repo` (string, did, required): DID of the repository as minted by the knot.
* `webhook` (string, required): Webhook ID to update.
* `url` (string, uri)
* `secret` (string)
* `active` (boolean)
* `events` (array of `org.tangled.webhook.defs#eventType`)

Errors:

* `WebhookNotFound`