Integrations

Integrations connect Cortex to external services so agents can read from and write to third-party platforms. Each integration stores encrypted credentials and exposes a sync and test mechanism.

Base path: /api/integrations

All endpoints require Authorization: Bearer <token>.

---

Supported Providers

Provider	Type	Description
github	Development	Repository access, issues, PRs
discord	Communication	Messages and channel management
slack	Communication	Messages, channels, slash commands
notion	Knowledge	Pages, databases, and blocks
linear	Project Management	Issues, projects, and cycles
gmail	Email	Send and receive via Gmail
zapier	Automation	Trigger Zaps and multi-step workflows
webhook	Custom	Generic outbound HTTP webhooks
custom	Custom	Arbitrary API with user-defined config

---

List Integrations

GET /api/integrations

Query parameters:

Parameter	Type	Description
provider	string	Filter by provider type
status	string	connected, error, pending
limit	number	Default 20
offset	number	Default 0

Response:

{
  "success": true,
  "data": [
    {
      "id": "int_01J...",
      "provider": "github",
      "name": "Acrobi GitHub",
      "status": "connected",
      "lastSyncAt": "2026-04-03T10:00:00Z",
      "createdAt": "2026-02-01T09:00:00Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 3 }
}

curl:

curl "https://api.cortex.acrobi.com/api/integrations?provider=github" \
  -H "Authorization: Bearer <token>"

---

Create Integration

POST /api/integrations

Request body:

{
  "provider": "github",
  "name": "Acrobi GitHub",
  "config": {
    "accessToken": "ghp_...",
    "org": "Acrobi",
    "defaultRepo": "cortex"
  }
}

Field	Type	Required	Description
provider	string	Yes	Provider identifier (see table above)
name	string	Yes	Human-readable label
config	object	Yes	Provider-specific credentials and settings

Credentials

Credentials in config are encrypted at rest using AES-GCM-256. They are never returned in plaintext after creation.

Response: 201 Created

{
  "success": true,
  "data": {
    "id": "int_01J...",
    "provider": "github",
    "name": "Acrobi GitHub",
    "status": "pending",
    "createdAt": "2026-04-03T12:00:00Z"
  }
}

curl:

curl -X POST "https://api.cortex.acrobi.com/api/integrations" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "name": "Acrobi GitHub",
    "config": { "accessToken": "ghp_...", "org": "Acrobi" }
  }'

---

Get Integration

GET /api/integrations/:id

Returns integration metadata. Credentials in config are masked — sensitive fields are replaced with "***".

Response:

{
  "success": true,
  "data": {
    "id": "int_01J...",
    "provider": "github",
    "name": "Acrobi GitHub",
    "status": "connected",
    "config": {
      "accessToken": "***",
      "org": "Acrobi",
      "defaultRepo": "cortex"
    },
    "lastSyncAt": "2026-04-03T10:00:00Z",
    "createdAt": "2026-02-01T09:00:00Z",
    "updatedAt": "2026-04-03T10:00:00Z"
  }
}

---

Update Integration

PATCH /api/integrations/:id

Update the name or config fields. Only provided config keys are updated — omitted keys retain their current (encrypted) values.

Request body:

{
  "name": "Acrobi GitHub (Main)",
  "config": {
    "defaultRepo": "cortex-v2"
  }
}

Response: 200 OK — returns updated integration with masked credentials.

---

Delete Integration

DELETE /api/integrations/:id

Removes the integration and destroys all stored credentials.

Response:

{ "success": true }

---

Sync Integration

Triggers a manual sync — pulls the latest data from the external provider into Cortex (e.g. fetch new GitHub issues, import Notion pages).

POST /api/integrations/:id/sync

Request body:

{
  "scope": "issues",
  "since": "2026-04-01T00:00:00Z"
}

Field	Type	Required	Description
scope	string	No	Provider-specific scope to sync (omit for full sync)
since	string	No	ISO 8601 timestamp to sync from

Response: 200 OK

{
  "success": true,
  "data": {
    "syncId": "sync_01J...",
    "status": "running",
    "startedAt": "2026-04-03T12:00:00Z"
  }
}

---

Test Integration

Sends a lightweight ping to verify credentials are valid and the external service is reachable.

POST /api/integrations/:id/test

No request body required.

Response: 200 OK

{
  "success": true,
  "data": {
    "connected": true,
    "provider": "github",
    "latencyMs": 142,
    "details": {
      "authenticatedAs": "acrobi-bot",
      "scopes": ["repo", "read:org"]
    }
  }
}

If the test fails:

{
  "success": false,
  "data": {
    "connected": false,
    "provider": "github",
    "error": "401 Bad credentials — token may have expired"
  }
}

curl:

curl -X POST "https://api.cortex.acrobi.com/api/integrations/int_01J.../test" \
  -H "Authorization: Bearer <token>"