API

Complete reference for the Bindplane REST API.

The Bindplane API provides programmatic access to all Bindplane functionality. This documentation covers all available endpoints organized by resource type.

Availability

The Bindplane API is available for Growth and Enterprise customers.

Authentication

All API requests require authentication using an API key. Include your API key in the X-Bindplane-Api-Key header:

curl -H "X-Bindplane-Api-Key: your-api-key" https://app.bindplane.com/v1/endpoint

Base URL

• Cloud: https://app.bindplane.com

• Self-hosted: https://your-bindplane-instance.com

Swagger

• OpenAPI: https://app.bindplane.com/swagger/index.html

API Endpoints

Accounts

• List Accounts - GET /v1/accounts

• Get Account by ID - GET /v1/accounts/{id}

• Create Account - POST /v1/accounts

• Update Account - PATCH /v1/accounts

• Update Current Account - PATCH /v1/accounts/current

• Delete Account - DELETE /v1/accounts/{id}

Agent Types

• List Agent Types - GET /v1/agent-types

• Get Agent Type by Name - GET /v1/agent-type/{name}

• Delete Agent Type - DELETE /v1/agent-types/{name}

Agent Versions

• List Agent Versions - GET /v1/agent-versions

• Get Agent Version by Name - GET /v1/agent-version/{name}

• Get Install Command - GET /v1/agent-versions/{type}/{version}/install-command

• Sync Agent Version - POST /v1/agent-versions/{type}/{version}/sync

• Delete Agent Version - DELETE /v1/agent-version/{name}

Agents

• List Agents - GET /v1/agents

• Get Agent by ID - GET /v1/agents/{id}

• Get Agent Configuration - GET /v1/agents/{id}/configuration

• Get Agent Labels - GET /v1/agents/{id}/labels

• Update Agent Labels - PATCH /v1/agents/{id}/labels

• Update Agent Version - POST /v1/agents/{id}/version

• Disconnect Agent - POST /v1/agents/{id}/disconnect

• Update Agent Labels (Bulk) - PATCH /v1/agents/labels

• Update Agent Version (Bulk) - PATCH /v1/agents/version

• Delete Agents - DELETE /v1/agents

Audit Events

• List Audit Events - GET /v1/audit-events

• Download Audit Events - GET /v1/audit-events/download

Available Components

• List Available Components - GET /v1/available-components

• Get Available Component by Hash - GET /v1/available-components/{hash}

Configurations

• List Configurations - GET /v1/configurations

• Get Configuration by Name - GET /v1/configurations/{name}

• Copy Configuration - POST /v1/configurations/{name}/copy

• Revert Configuration - PUT /v1/configurations/{name}/revert

• Delete Configuration - DELETE /v1/configurations/{name}

Destination Types

• List Destination Types - GET /v1/destination-types

• Get Destination Type by Name - GET /v1/destination-types/{name}

• Delete Destination Type - DELETE /v1/destination-types/{name}

Destinations

• List Destinations - GET /v1/destinations

• Get Destination by Name - GET /v1/destinations/{name}

• Delete Destination - DELETE /v1/destinations/{name}

Extension Types

• List Extension Types - GET /v1/extension-types

• Get Extension Type by Name - GET /v1/extension-types/{name}

• Delete Extension Type - DELETE /v1/extension-types/{name}

Extensions

• List Extensions - GET /v1/extensions

• Get Extension by Name - GET /v1/extensions/{name}

• Delete Extension - DELETE /v1/extensions/{name}

Fleets

• List Fleets - GET /v1/fleets

Organizations

• List Organizations - GET /v1/organizations

• Create Organization - POST /v1/organizations

• Get Organization by Name - GET /v1/organizations/{name}

• Update Organization Metadata - PATCH /v1/organizations/{id}/metadata

• Delete Organization - DELETE /v1/organizations/{id}

• Get Organization Accounts - GET /v1/organizations/accounts

• Get All Organization Accounts - GET /v1/organizations/accounts/all

• Get Organization Projects - GET /v1/organizations/projects

• Get All Organization Projects - GET /v1/organizations/projects/all

• Get Organization Users - GET /v1/organizations/users

• Verify Organization - PUT /v1/organizations/verify

• Update Organization License - PUT /v1/organizations/:id/license

Processor Types

• List Processor Types - GET /v1/processor-types

• Get Processor Type by Name - GET /v1/processor-types/{name}

• Delete Processor Type - DELETE /v1/processor-types/{name}

Processors

• List Processors - GET /v1/processors

• Get Processor by Name - GET /v1/processors/{name}

• Delete Processor - DELETE /v1/processors/{name}

Projects

• List Projects - GET /v1/projects

• Create Project - POST /v1/projects

• Get Project by ID - GET /v1/projects/{id}

• Update Project - PATCH /v1/projects

• Update Current Project - PATCH /v1/projects/current

• Update Project Next Login - PATCH /v1/projects/next-login

• Delete Project - DELETE /v1/projects/{id}

Recommendation Types

• List Recommendation Types - GET /v1/recommendation-types

• Get Recommendation Type by Name - GET /v1/recommendation-types/{name}

• Delete Recommendation Type - DELETE /v1/recommendation-types/{name}

Resources

• List Resources by Kind - GET /v1/resources/{kind}

• Get Resource by Kind and Name - GET /v1/resources/{kind}/{name}

• Delete Resource - DELETE /v1/resources/{kind}/{name}

Rollouts

• List Rollouts - GET /v1/rollouts

• Create Rollout - POST /v1/rollouts

• Get Rollout by Name - GET /v1/rollouts/{name}

• Get Rollout Status - GET /v1/rollouts/{name}/status

• Start Rollout - POST /v1/rollouts/{name}/start

• Update Rollout - POST /v1/rollouts/{name}/update

• Pause Rollout - PUT /v1/rollouts/{name}/pause

• Resume Rollout - PUT /v1/rollouts/{name}/resume

Secret Keys

• List Secret Keys - GET /v1/secret-keys

• Create Secret Key - POST /v1/secret-keys

• Set Default Secret Key - POST /v1/secret-keys/{key}/default

• Delete Secret Key - DELETE /v1/secret-keys/{key}

Source Types

• List Source Types - GET /v1/source-types

• Get Source Type by Name - GET /v1/source-types/{name}

• Delete Source Type - DELETE /v1/source-types/{name}

Sources

• List Sources - GET /v1/sources

• Get Source by Name - GET /v1/sources/{name}

• Delete Source - DELETE /v1/sources/{name}

Users

• List Users - GET /v1/users

• Create User - POST /v1/users

• Get User by ID - GET /v1/users/{id}

• Delete User - DELETE /v1/users/{id}

System

• Get Version - GET /v1/version

• Accept EULA - PUT /v1/accept-eula

• Apply Changes - POST /v1/apply

• Delete Resources - POST /v1/delete

• Get Resource History - GET /v1/{kind}/{name}/history

• Update System License Key - PUT /v1/system/v1/license-key

• Update Organization License - PUT /v1/organization-license

• Create Offline Agent Version - POST /v1/offline-agent-version/{version}

• Stream Offline Agent Version - POST /v1/offline-agent-version/{version}/stream

Response Format

All API responses are returned in JSON format. Successful responses typically return a 200 status code with the requested data.

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

• 200 OK - Request successful

• 201 Created - Resource created successfully

• 400 Bad Request - Invalid request parameters

• 401 Unauthorized - Missing or invalid API key

• 403 Forbidden - Insufficient permissions

• 404 Not Found - Resource not found

• 500 Internal Server Error - Server error

Error responses include a JSON object with error details:

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

Rate Limiting

API requests are subject to rate limiting. If you exceed the rate limit, you'll receive a 429 status code. Implement exponential backoff in your applications to handle rate limiting gracefully.