# API

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

{% hint style="info" %}
**Availability**

The Bindplane API is available for [Growth and Enterprise customers](https://bindplane.com/pricing).
{% endhint %}

### Authentication

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

```bash
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:

```json
{
  "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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bindplane.com/cli-and-api/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.