<commit_before>---
title: Director API v1
---

<p class="note">Note: Before using the Director API directly, we strongly encourage to consider using the CLI for automation such as performing a scheduled deploy from a CI. We hope that you will open a <a href="https://github.com/cloudfoundry/bosh/issues">GitHub issue</a> to share your use cases so that we can suggest or possibly make additions to the CLI.</a></p>

This document lists common API endpoints provided by the Director.

---
## <a id="overview"></a> Overview

### <a id="auth"></a> Security

All API access should be done over verified HTTPS.

The Director can be configured in two authentication modes: [basic auth](director-users.html#preconfigured) and [UAA](director-users-uaa.html). [Info endpoint](#info) does not require any authentication and can be used to determine which authentication mechanism to use. All other endpoints require authentication.

`401 Unauthorized` will be returned for requests that contain an invalid basic auth credentials or an invalid/expired UAA access token.

### <a id="http-verbs"></a> HTTP verbs

Standard HTTP verb semantics are followed:

| Verb | Description |
-------|-------------|
| GET  | Used for retrieving resources. |
| POST/PUT | Used for creating/updating resources. |
| DELETE | Used for deleting resources. |

### <a id="http-verbs"></a> HTTP redirects

Any request may result in a redirection. Receiving an HTTP redirection is not an error and clients should follow that redirect. Redirect responses will have a Location header field. Clients should use same authentication method when following a redirect.

### <a id="rate-limiting"></a> Rate limiting

Currently no rate limiting is performed.

### <a id="pagination"></a> Pagination

Currently none of the resources are paginated.

### <a id="long-running-ops"></a> Long running operations (aka Director tasks)

Certain requests result in complex and potentially long running operations against the IaaS, blobstore, or other resources. [`POST /deployments`](#post-deployment) is a good example. Such requests start a [Director task](director-tasks.html) and continue running on the Director after response is returned. Response to such request will be a `302 Moved Temporarily` redirect to a created task resource.

Once a Director task is created, clients can follow its progress by polling [`GET /tasks/{id}`](#get-task) to find out its state. While waiting for the task to finish, different types of logs ([event](#get-task-event), [result](#get-task-result), [debug](#get-task-debug) information, etc.) can be followed to gain insight into what the task is doing.

---
## <a id="general"></a> General

### <a id="info"></a> `GET /info`: Info

#### Response body schema

**[root]** [Hash]: Director details.

- **name** [String]: Name of the Director.
- **uuid** [String]: Unique ID of the Director.
- **version** [String]: Version of the Director software.
- **user** [String or null]: Logged in user's user name if authentication is provided, otherwise null.
- **cpi** [String]: Name of the CPI the Director will use.
- **user_authentication** [Hash]:
	- **type** [String]: Type of the authentication the Director is configured to expect.
	- **options** [Hash]: Additional information provided to how authentication should be performed.

#### Notes

- This is the only endpoint that does not require authentication.
- In future `version` will contain version of the deployed BOSH release.

#### Example

<pre class="terminal">
$ curl -s -k https://192.168.50.4:25555/info | jq .
</pre>

```yaml
{
  "name": "Bosh Lite Director",
  "uuid": "2daf673a-9755-4b4f-aa6d-3632fbed8012",
  "version": "1.3126.0 (00000000)",
  "user": null,
  "cpi": "warden_cpi",
  "user_authentication": {
    "type": "basic",
    "options": {}
  }
}
```<commit_msg>Add config server to info endpoint<commit_after>---
title: Director API v1
---

<p class="note">Note: Before using the Director API directly, we strongly encourage to consider using the CLI for automation such as performing a scheduled deploy from a CI. We hope that you will open a <a href="https://github.com/cloudfoundry/bosh/issues">GitHub issue</a> to share your use cases so that we can suggest or possibly make additions to the CLI.</a></p>

This document lists common API endpoints provided by the Director.

---
## <a id="overview"></a> Overview

### <a id="auth"></a> Security

All API access should be done over verified HTTPS.

The Director can be configured in two authentication modes: [basic auth](director-users.html#preconfigured) and [UAA](director-users-uaa.html). [Info endpoint](#info) does not require any authentication and can be used to determine which authentication mechanism to use. All other endpoints require authentication.

`401 Unauthorized` will be returned for requests that contain an invalid basic auth credentials or an invalid/expired UAA access token.

### <a id="http-verbs"></a> HTTP verbs

Standard HTTP verb semantics are followed:

| Verb | Description |
-------|-------------|
| GET  | Used for retrieving resources. |
| POST/PUT | Used for creating/updating resources. |
| DELETE | Used for deleting resources. |

### <a id="http-verbs"></a> HTTP redirects

Any request may result in a redirection. Receiving an HTTP redirection is not an error and clients should follow that redirect. Redirect responses will have a Location header field. Clients should use same authentication method when following a redirect.

### <a id="rate-limiting"></a> Rate limiting

Currently no rate limiting is performed.

### <a id="pagination"></a> Pagination

Currently none of the resources are paginated.

### <a id="long-running-ops"></a> Long running operations (aka Director tasks)

Certain requests result in complex and potentially long running operations against the IaaS, blobstore, or other resources. [`POST /deployments`](#post-deployment) is a good example. Such requests start a [Director task](director-tasks.html) and continue running on the Director after response is returned. Response to such request will be a `302 Moved Temporarily` redirect to a created task resource.

Once a Director task is created, clients can follow its progress by polling [`GET /tasks/{id}`](#get-task) to find out its state. While waiting for the task to finish, different types of logs ([event](#get-task-event), [result](#get-task-result), [debug](#get-task-debug) information, etc.) can be followed to gain insight into what the task is doing.

---
## <a id="general"></a> General

### <a id="info"></a> `GET /info`: Info

#### Response body schema

**[root]** [Hash]: Director details.

- **name** [String]: Name of the Director.
- **uuid** [String]: Unique ID of the Director.
- **version** [String]: Version of the Director software.
- **user** [String or null]: Logged in user's user name if authentication is provided, otherwise null.
- **cpi** [String]: Name of the CPI the Director will use.
- **user_authentication** [Hash]:
	- **type** [String]: Type of the authentication the Director is configured to expect.
	- **options** [Hash]: Additional information provided to how authentication should be performed.
- **features** [Hash]:
	- **config_server** [Hash]:
		- **status** [Boolean]: Default false.
		- **extras** [Hash]:
			- **urls** [Array]: List of URLs for the Config Server.

#### Notes

- This is the only endpoint that does not require authentication.
- In future `version` will contain version of the deployed BOSH release.

#### Example

<pre class="terminal">
$ curl -s -k https://192.168.50.4:25555/info | jq .
</pre>

```yaml
{
  "name": "Bosh Lite Director",
  "uuid": "2daf673a-9755-4b4f-aa6d-3632fbed8012",
  "version": "1.3126.0 (00000000)",
  "user": null,
  "cpi": "warden_cpi",
  "user_authentication": {
    "type": "basic",
    "options": {}
  }
}
```
{'fraction_non_alphanumeric': 0.127170582226762, 'fraction_numerical': 0.013789581205311542, 'mean_word_length': 4.332198774676651, 'pattern_counts': {'":': 16, '<': 53, '<?xml version=': 0, '>': 53, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 2, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6510173', 'n_tokens_mistral': 2269, 'n_tokens_neox': 2126, 'n_words': 974}