Platform API Reference

Use the Platform API to read and update organization details, manage projects, and manage project API keys.

Authentication

Platform endpoints authenticate with an organization-scoped API key — a key created at the organization level rather than inside a single project. Create one in your organization API key settings, then pass it as a bearer token on every request.

An organization key is not limited to the Platform API. It can also call the Event Gateway API and Outpost API for projects it can access. Include the Project-ID header with either project API to select the project.

Access depends on the key's project grants and scopes. See API Keys for project access, available scopes, and key rotation.

Example authenticated request

cURL

curl "https://api.hookdeck.com/2026-09-01/projects"
  -H "Content-Type: application/json"
  -H "Authorization: Bearer $ORGANIZATION_API_KEY"

Organizations

An organization is the top-level entity that owns projects, members, and subscriptions.

Example organization object

JSON

{
  "id": "org_9bML1qH2vXp3",
  "name": "Acme Inc",
  "slug": "acme-inc",
  "domains": [
    "acme.com"
  ],
  "sandbox": false,
  "mfa_required": false,
  "feature_flags": {},
  "sso_enabled": false,
  "directory_sync_enabled": false,
  "updated_at": "2025-06-01T12:00:00.000Z",
  "created_at": "2025-01-15T08:30:00.000Z"
}

Get the current organization

GET

/organizations/current

Request

Shell

curl -X GET \
  "https://api.hookdeck.com/2026-09-01/organizations/current" \
  -H "Authorization: Bearer $ORGANIZATION_API_KEY"

Response

JSON

{
  "id": "org_9bML1qH2vXp3",
  "name": "Acme Inc",
  "slug": "acme-inc",
  "domains": [
    "acme.com"
  ],
  "sandbox": false,
  "mfa_required": false,
  "feature_flags": {},
  "sso_enabled": false,
  "directory_sync_enabled": false,
  "updated_at": "2025-06-01T12:00:00.000Z",
  "created_at": "2025-01-15T08:30:00.000Z"
}

Update the current organization

PUT

/organizations/current

Request

Shell

curl -X PUT \
  "https://api.hookdeck.com/2026-09-01/organizations/current" \
  -H "Authorization: Bearer $ORGANIZATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Inc"
}'

Response

JSON

{
  "id": "org_9bML1qH2vXp3",
  "name": "Acme Inc",
  "slug": "acme-inc",
  "domains": [
    "acme.com"
  ],
  "sandbox": false,
  "mfa_required": false,
  "feature_flags": {},
  "sso_enabled": false,
  "directory_sync_enabled": false,
  "updated_at": "2025-06-01T12:00:00.000Z",
  "created_at": "2025-01-15T08:30:00.000Z"
}

List API keys

List the active organization and project API keys of the current organization.

GET

/organizations/current/api-keys

Request

Shell

curl -X GET \
  "https://api.hookdeck.com/2026-09-01/organizations/current/api-keys" \
  -H "Authorization: Bearer $ORGANIZATION_API_KEY"

Response

JSON

[
  {
    "id": "apk_3fVq8tR1nZx0",
    "label": "CI pipeline",
    "key": "hd_org_a1b2c3d4e5f6...",
    "team_id": null,
    "organization_id": "org_9bML1qH2vXp3",
    "key_fingerprint": "a1b2c3d4",
    "scopes": [
      "gateway.sources.read",
      "gateway.events.write"
    ],
    "grants": {
      "tm_9bML1qH2vXp3": {
        "scopes": [
          "gateway.events.read"
        ]
      }
    },
    "expires_at": null,
    "updated_at": "2025-06-01T12:00:00.000Z",
    "created_at": "2025-01-15T08:30:00.000Z"
  }
]

Create an API key

Create an organization or project API key. Creating organization API keys requires an admin session. Organization API keys can only create project keys, and only with scopes they hold on that project.

POST

/organizations/current/api-keys

Request

Shell

curl -X POST \
  "https://api.hookdeck.com/2026-09-01/organizations/current/api-keys" \
  -H "Authorization: Bearer $ORGANIZATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "CI pipeline",
  "type": "organization",
  "scopes": [
    "gateway.sources.read"
  ],
  "grants": {}
}'

Response

JSON

{
  "id": "apk_3fVq8tR1nZx0",
  "label": "CI pipeline",
  "key": "hd_org_a1b2c3d4e5f6...",
  "team_id": null,
  "organization_id": "org_9bML1qH2vXp3",
  "key_fingerprint": "a1b2c3d4",
  "scopes": [
    "gateway.sources.read",
    "gateway.events.write"
  ],
  "grants": {
    "tm_9bML1qH2vXp3": {
      "scopes": [
        "gateway.events.read"
      ]
    }
  },
  "expires_at": null,
  "updated_at": "2025-06-01T12:00:00.000Z",
  "created_at": "2025-01-15T08:30:00.000Z"
}

Roll an API key

Roll an API key: the current key expires after the rollover delay and a replacement key is returned. Organization API keys can only roll project keys whose scopes they hold on that project.

POST

/organizations/current/api-keys/id/roll

Request

Shell

curl -X POST \
  "https://api.hookdeck.com/2026-09-01/organizations/current/api-keys/<id>/roll" \
  -H "Authorization: Bearer $ORGANIZATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "delay_sec": 3600
}'

Response

JSON

{
  "id": "apk_3fVq8tR1nZx0",
  "label": "CI pipeline",
  "key": "hd_org_a1b2c3d4e5f6...",
  "team_id": null,
  "organization_id": "org_9bML1qH2vXp3",
  "key_fingerprint": "a1b2c3d4",
  "scopes": [
    "gateway.sources.read",
    "gateway.events.write"
  ],
  "grants": {
    "tm_9bML1qH2vXp3": {
      "scopes": [
        "gateway.events.read"
      ]
    }
  },
  "expires_at": null,
  "updated_at": "2025-06-01T12:00:00.000Z",
  "created_at": "2025-01-15T08:30:00.000Z"
}

Update an API key

Update the scopes and grants of an API key. The secret is unchanged.

PUT

/organizations/current/api-keys/id

Request

Shell

curl -X PUT \
  "https://api.hookdeck.com/2026-09-01/organizations/current/api-keys/<id>" \
  -H "Authorization: Bearer $ORGANIZATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "scopes": [
    "gateway.sources.read"
  ],
  "grants": {}
}'

Response

JSON

{
  "id": "apk_3fVq8tR1nZx0",
  "label": "CI pipeline",
  "key": "hd_org_a1b2c3d4e5f6...",
  "team_id": null,
  "organization_id": "org_9bML1qH2vXp3",
  "key_fingerprint": "a1b2c3d4",
  "scopes": [
    "gateway.sources.read",
    "gateway.events.write"
  ],
  "grants": {
    "tm_9bML1qH2vXp3": {
      "scopes": [
        "gateway.events.read"
      ]
    }
  },
  "expires_at": null,
  "updated_at": "2025-06-01T12:00:00.000Z",
  "created_at": "2025-01-15T08:30:00.000Z"
}

Delete an API key

Delete an API key. The key stops authenticating immediately.

DELETE

/organizations/current/api-keys/id

Request

Shell

curl -X DELETE \
  "https://api.hookdeck.com/2026-09-01/organizations/current/api-keys/<id>" \
  -H "Authorization: Bearer $ORGANIZATION_API_KEY"

Response

JSON

{
  "id": "apk_3fVq8tR1nZx0"
}

API Keys

Example apikey object

JSON

{
  "id": "apk_3fVq8tR1nZx0",
  "label": "CI pipeline",
  "key": "hd_org_a1b2c3d4e5f6...",
  "team_id": null,
  "organization_id": "org_9bML1qH2vXp3",
  "key_fingerprint": "a1b2c3d4",
  "scopes": [
    "gateway.sources.read",
    "gateway.events.write"
  ],
  "grants": {
    "tm_9bML1qH2vXp3": {
      "scopes": [
        "gateway.events.read"
      ]
    }
  },
  "expires_at": null,
  "updated_at": "2025-06-01T12:00:00.000Z",
  "created_at": "2025-01-15T08:30:00.000Z"
}

Projects

A project is an isolated environment that owns sources, destinations, and connections within an organization.

Example project object

JSON

{
  "id": "tm_7yKd3nF0pQ2a",
  "organization_id": "org_9bML1qH2vXp3",
  "name": "Production",
  "type": "event_gateway",
  "private": false,
  "is_guest": false,
  "static_ip_proxy": false,
  "notification_methods": [
    "email"
  ],
  "webhook_topics": [],
  "webhook_source_id": null,
  "custom_hostnames": [],
  "directory_sync_enabled": false,
  "headers_prefix": "X-Production",
  "max_events_per_second": 100,
  "notification_preferences": {
    "project_throughput_exceed": true
  },
  "updated_at": "2025-06-01T12:00:00.000Z",
  "created_at": "2025-01-15T08:30:00.000Z"
}

List projects

List all projects for the authenticated organization or user.

GET

/projects

Request

Shell

curl -X GET \
  "https://api.hookdeck.com/2026-09-01/projects" \
  -H "Authorization: Bearer $ORGANIZATION_API_KEY"

Response

JSON

[
  {
    "id": "tm_7yKd3nF0pQ2a",
    "organization_id": "org_9bML1qH2vXp3",
    "name": "Production",
    "type": "event_gateway",
    "private": false,
    "is_guest": false,
    "static_ip_proxy": false,
    "notification_methods": [
      "email"
    ],
    "webhook_topics": [],
    "webhook_source_id": null,
    "custom_hostnames": [],
    "directory_sync_enabled": false,
    "headers_prefix": "X-Production",
    "max_events_per_second": 100,
    "notification_preferences": {
      "project_throughput_exceed": true
    },
    "updated_at": "2025-06-01T12:00:00.000Z",
    "created_at": "2025-01-15T08:30:00.000Z"
  }
]

Create a project

Create a new project within an organization. An organization API key restricted to selected projects is automatically granted access to the project it creates.

POST

/projects

Request

Shell

curl -X POST \
  "https://api.hookdeck.com/2026-09-01/projects" \
  -H "Authorization: Bearer $ORGANIZATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Staging",
  "organization_id": "org_9bML1qH2vXp3",
  "private": false,
  "type": "event_gateway"
}'

Response

JSON

{
  "id": "tm_7yKd3nF0pQ2a",
  "organization_id": "org_9bML1qH2vXp3",
  "name": "Production",
  "type": "event_gateway",
  "private": false,
  "is_guest": false,
  "static_ip_proxy": false,
  "notification_methods": [
    "email"
  ],
  "webhook_topics": [],
  "webhook_source_id": null,
  "custom_hostnames": [],
  "directory_sync_enabled": false,
  "headers_prefix": "X-Production",
  "max_events_per_second": 100,
  "notification_preferences": {
    "project_throughput_exceed": true
  },
  "updated_at": "2025-06-01T12:00:00.000Z",
  "created_at": "2025-01-15T08:30:00.000Z"
}

Get a project

Retrieve a project by ID.

GET

/projects/id

Request

Shell

curl -X GET \
  "https://api.hookdeck.com/2026-09-01/projects/<id>" \
  -H "Authorization: Bearer $ORGANIZATION_API_KEY"

Response

JSON

{
  "id": "tm_7yKd3nF0pQ2a",
  "organization_id": "org_9bML1qH2vXp3",
  "name": "Production",
  "type": "event_gateway",
  "private": false,
  "is_guest": false,
  "static_ip_proxy": false,
  "notification_methods": [
    "email"
  ],
  "webhook_topics": [],
  "webhook_source_id": null,
  "custom_hostnames": [],
  "directory_sync_enabled": false,
  "headers_prefix": "X-Production",
  "max_events_per_second": 100,
  "notification_preferences": {
    "project_throughput_exceed": true
  },
  "updated_at": "2025-06-01T12:00:00.000Z",
  "created_at": "2025-01-15T08:30:00.000Z"
}

Update a project

Update a project by ID.

PUT

/projects/id

Request

Shell

curl -X PUT \
  "https://api.hookdeck.com/2026-09-01/projects/<id>" \
  -H "Authorization: Bearer $ORGANIZATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "headers_prefix": "X-Production",
  "name": "Production",
  "context": {},
  "notification_methods": [
    "email"
  ],
  "notification_preferences": {
    "project_throughput_exceed": true
  },
  "private": false
}'

Response

JSON

{
  "id": "tm_7yKd3nF0pQ2a",
  "organization_id": "org_9bML1qH2vXp3",
  "name": "Production",
  "type": "event_gateway",
  "private": false,
  "is_guest": false,
  "static_ip_proxy": false,
  "notification_methods": [
    "email"
  ],
  "webhook_topics": [],
  "webhook_source_id": null,
  "custom_hostnames": [],
  "directory_sync_enabled": false,
  "headers_prefix": "X-Production",
  "max_events_per_second": 100,
  "notification_preferences": {
    "project_throughput_exceed": true
  },
  "updated_at": "2025-06-01T12:00:00.000Z",
  "created_at": "2025-01-15T08:30:00.000Z"
}

Delete a project

Delete a project by ID.

DELETE

/projects/id

Request

Shell

curl -X DELETE \
  "https://api.hookdeck.com/2026-09-01/projects/<id>" \
  -H "Authorization: Bearer $ORGANIZATION_API_KEY"

Response

JSON

{
  "id": "tm_7yKd3nF0pQ2a"
}