Platform API Reference

Platform API

The Platform API manages the organization and projects that hold your Event Gateway resources. Use it to read and update organization details, list and create projects, and manage organization 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 be granted a set of projects, and its scopes apply within each of them, so the same key can call Event Gateway endpoints in those projects when it carries the matching gateway.* scopes. A key created without an explicit scope list defaults to *, which reaches every project in the organization.

Organization endpoints require organizations.read or organizations.write, and project endpoints require projects.read or projects.write. A request whose key is missing the scope its route requires returns 403.

Example authenticated request

cURL

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

Base URL

Platform endpoints share the base URL and versioning of the Hookdeck REST API:

https://api.hookdeck.com/2026-09-01

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"
}

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,
  "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,
    "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,
  "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,
  "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"
  ],
  "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,
  "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"
}