> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macroscope.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API

> Trigger Macroscope's agent programmatically via webhooks

<Note>To use the API,  you must configure Status. To configure Status, click on Status in the left sidebar, then complete the Product Overview and Sprint Cadence. Once your backfill has finished, you'll be able to use the API.</Note>
Macroscope exposes an inbound webhook that triggers the agent. It's the same agent you use in Slack and GitHub, but invoked via HTTP so you can call it from CI pipelines, scripts, cron jobs, or any other system.

When the agent finishes, Macroscope forwards the results to a destination you specify: a Slack channel or an external URL of your choice.

## Setup

1. Go to **Settings → Connections → Webhooks**
2. Click **Add Webhook** and give it a name (e.g. `ci-pipeline`)
3. Copy your **API key**. It's shown once and can't be retrieved later.
4. Copy your **Trigger URL**. You can access it anytime in Settings → Connections → Webhooks.

Your **Trigger URL** will follow this format:

```
POST https://hooks.macroscope.com/api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-webhook-trigger
```

## URL Allowlisting

<a id="allowed-external-urls" />

If you want Macroscope to deliver results to an external URL (rather than Slack), that URL must be allowlisted first. For example, if you're routing results to a Zapier or n8n webhook endpoint, add that URL here. Manage the list in **Settings → Connections → Webhooks → Allowed External URLs**. Only GitHub organization admins can add or remove URLs. Must be HTTPS.

## Request

Every request needs two headers:

```bash theme={null}
-H "Content-Type: application/json"
-H "X-Webhook-Secret: your-api-key"
```

POST a JSON body to your trigger URL:

<ParamField body="query" type="string" required>
  The question to ask the agent.
</ParamField>

<ParamField body="responseDestination" type="object" required>
  Where to deliver the results. Use `slackChannelId` (string) to post to Slack, or `webhookUrl` (string) to POST to an external URL (must be [allowlisted](#allowed-external-urls)). Optionally include `slackThreadTs` (string) to reply in a specific Slack thread.
</ParamField>

<ParamField body="timezone" type="string">
  IANA timezone (e.g. `America/Los_Angeles`). Affects date references in the query.
</ParamField>

The request returns `202 Accepted` with a `workflowId`:

```json theme={null}
{ "workflowId": "abc-123-def-456" }
```

## Example Requests

**Deliver results to Slack:**

```bash theme={null}
curl -X POST \
  "https://hooks.macroscope.com/api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-webhook-trigger" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: your-api-key" \
  -d '{
    "query": "What were the main changes this week?",
    "responseDestination": { "slackChannelId": "C0123456789" },
    "timezone": "America/Los_Angeles"
  }'
```

**Deliver results to a Slack thread:**

```bash theme={null}
curl -X POST \
  "https://hooks.macroscope.com/api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-webhook-trigger" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: your-api-key" \
  -d '{
    "query": "Investigate this alert and respond in thread",
    "responseDestination": {
      "slackChannelId": "C0123456789",
      "slackThreadTs": "1234567890.123456"
    },
    "timezone": "America/Los_Angeles"
  }'
```

**Deliver results to an external URL:**

```bash theme={null}
curl -X POST \
  "https://hooks.macroscope.com/api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-webhook-trigger" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: your-api-key" \
  -d '{
    "query": "What were the main changes this week?",
    "responseDestination": { "webhookUrl": "https://your-endpoint.com/callback" },
    "timezone": "America/Los_Angeles"
  }'
```

## Response Payload

When the agent finishes, Macroscope POSTs this to your Slack channel or URL:

```json theme={null}
{
  "query": "What were the main changes this week?",
  "response": "Here are the main changes...",
  "workflowId": "abc-123-def-456"
}
```

## Error Codes

| Code  | Meaning                                          |
| ----- | ------------------------------------------------ |
| `202` | Query accepted.                                  |
| `400` | Malformed request or missing `query`.            |
| `401` | Missing or invalid `X-Webhook-Secret`.           |
| `403` | Wrong workspace, or webhook URL not allowlisted. |

## Use Cases

* **Post-deploy summaries**: GitHub Actions runs a deploy, triggers a webhook asking "what changed in this release?", and Macroscope posts a plain-English summary to your team's Slack channel.
* **Incident response**: wire a PagerDuty or Sentry alert to trigger a Macroscope webhook. The agent can investigate the error, open a PR with a proposed fix, assign the most relevant teammate as a reviewer, and post a summary to your on-call Slack channel.
* **No-code automations**: a Zapier or n8n workflow triggers Macroscope every Monday morning to generate a weekly engineering digest and routes the answer to email, Notion, or wherever your team tracks updates.