<commit_before>---
title: "Namespaces API"
description: "The Sensu namespace API provides HTTP access to namespace data. This reference includes examples for returning lists of namespaces, creating Sensu namespaces, and more. Read on for the full reference."
version: "5.16"
product: "Sensu Go"
menu:
  sensu-go-5.16:
    parent: api
---

- [The `/namespaces` API endpoint](#the-namespaces-api-endpoint)
	- [`/namespaces` (GET)](#namespaces-get)
	- [`/namespaces` (POST)](#namespaces-post)
- [The `/namespaces/:namespace` API endpoint](#the-namespacesnamespace-api-endpoint)
  - [`/namespaces/:namespace` (PUT)](#namespacesnamespace-put)
  - [`/namespaces/:namespace` (DELETE)](#namespacesnamespace-delete)
- [The `/user-namespaces` API endpoint](#the-user-namespaces-api-endpoint)
  - [`/user-namespaces` (GET)](#user-namespaces-get)

## The `/namespaces` API endpoint

### `/namespaces` (GET)

The `/namespaces` API endpoint provides HTTP GET access to [namespace][1] data.

#### EXAMPLE {#namespaces-get-example}

The following example demonstrates a request to the `/namespaces` API endpoint, resulting in a JSON array that contains [namespace definitions][1].

{{< highlight shell >}}
curl http://127.0.0.1:8080/api/core/v2/namespaces -H "Authorization: Bearer $SENSU_TOKEN"
[
  {
    "name": "default"
  },
  {
    "name": "development"
  }
]
{{< /highlight >}}

#### API Specification {#namespaces-get-specification}

/namespaces (GET)  | 
---------------|------
description    | Returns the list of namespaces.
example url    | http://hostname:8080/api/core/v2/namespaces
pagination     | This endpoint supports pagination using the `limit` and `continue` query parameters. See the [API overview][2] for details.
response type  | Array
response codes | <ul><li>**Success**: 200 (OK)</li><li>**Error**: 500 (Internal Server Error)</li></ul>
output         | {{< highlight shell >}}
[
  {
    "name": "default"
  },
  {
    "name": "development"
  }
]
{{< /highlight >}}

### `/namespaces` (POST)

The `/namespaces` API endpoint provides HTTP POST access to create Sensu namespaces.

#### API Specification {#namespaces-post-specification}

/namespaces (POST) | 
----------------|------
description     | Creates a Sensu namespace.
example URL     | http://hostname:8080/api/core/v2/namespaces
payload         | {{< highlight shell >}}
{
  "name": "development"
}
{{< /highlight >}}
response codes  | <ul><li>**Success**: 200 (OK)</li><li>**Malformed**: 400 (Bad Request)</li><li>**Error**: 500 (Internal Server Error)</li></ul>

## The `/namespaces/:namespace` API endpoint {#the-namespacesnamespace-api-endpoint}

### `/namespaces/:namespace` (PUT) {#namespacesnamespace-put}

The `/namespaces/:namespace` API endpoint provides HTTP PUT access to create or update specific Sensu namespaces, by namespace name.

#### API Specification {#namespacesnamespace-put-specification}

/namespaces/:namespace (PUT) | 
----------------|------
description     | Creates or updates a Sensu namespace.
example URL     | http://hostname:8080/api/core/v2/namespaces/development
payload         | {{< highlight shell >}}
{
  "name": "development"
}
{{< /highlight >}}
response codes  | <ul><li>**Success**: 201 (Created)</li><li>**Malformed**: 400 (Bad Request)</li><li>**Error**: 500 (Internal Server Error)</li></ul>

### `/namespaces/:namespace` (DELETE) {#namespacesnamespace-delete}

The `/namespaces/:namespace` API endpoint provides HTTP DELETE access to delete a namespace from Sensu (specified by the namespace name).

#### EXAMPLE {#namespacesnamespace-delete-example}

The following example shows a request to the `/namespaces/:namespace` API endpoint to delete the namespace `development`, resulting in a successful HTTP `204 No Content` response.

{{< highlight shell >}}
curl -X DELETE \
-H "Authorization: Bearer $SENSU_TOKEN" \
http://127.0.0.1:8080/api/core/v2/namespaces/development

HTTP/1.1 204 No Content
{{< /highlight >}}

#### API Specification {#namespacesnamespace-delete-specification}

/namespaces/:namespace (DELETE) | 
--------------------------|------
description               | Removes the specified namespace from Sensu.
example url               | http://hostname:8080/api/core/v2/namespaces/development
response codes            | <ul><li>**Success**: 204 (No Content)</li><li>**Missing**: 404 (Not Found)</li><li>**Error**: 500 (Internal Server Error)</li></ul>

## The `/user-namespaces` API endpoint {#the-user-namespaces-api-endpoint}

### `/user-namespaces` (GET)

The `/user-namespaces` API endpoint provides HTTP GET access to the namespaces the user has access to.

#### EXAMPLE {#user-namespaces-get-example}

The following example demonstrates a request to the `/user-namespaces` API endpoint, resulting in a JSON array that contains the namespaces the user has access to.

{{< highlight shell >}}
curl http://127.0.0.1:8080/api/enterprise/user-namespaces -H "Authorization: Bearer $SENSU_TOKEN"
[
  {
    "name": "default"
  },
  {
    "name": "development"
  }
]
{{< /highlight >}}

#### API Specification {#namespaces-get-specification}

/user-namespaces (GET)  | 
---------------|------
description    | Returns the list of namespaces a user has access to.
example url    | http://hostname:8080/api/enterprise/user-namespaces
response type  | Array
response codes | <ul><li>**Success**: 200 (OK)</li><li>**Error**: 500 (Internal Server Error)</li></ul>
output         | {{< highlight shell >}}
[
  {
    "name": "default"
  },
  {
    "name": "development"
  }
]
{{< /highlight >}}<commit_msg>Add POST and PUT examples in namespaces API doc (#2061)<commit_after>---
title: "Namespaces API"
description: "The Sensu namespace API provides HTTP access to namespace data. This reference includes examples for returning lists of namespaces, creating Sensu namespaces, and more. Read on for the full reference."
version: "5.16"
product: "Sensu Go"
menu:
  sensu-go-5.16:
    parent: api
---

- [The `/namespaces` API endpoint](#the-namespaces-api-endpoint)
	- [`/namespaces` (GET)](#namespaces-get)
	- [`/namespaces` (POST)](#namespaces-post)
- [The `/namespaces/:namespace` API endpoint](#the-namespacesnamespace-api-endpoint)
  - [`/namespaces/:namespace` (PUT)](#namespacesnamespace-put)
  - [`/namespaces/:namespace` (DELETE)](#namespacesnamespace-delete)
- [The `/user-namespaces` API endpoint](#the-user-namespaces-api-endpoint)
  - [`/user-namespaces` (GET)](#user-namespaces-get)

## The `/namespaces` API endpoint

### `/namespaces` (GET)

The `/namespaces` API endpoint provides HTTP GET access to [namespace][1] data.

#### EXAMPLE {#namespaces-get-example}

The following example demonstrates a request to the `/namespaces` API endpoint, resulting in a JSON array that contains [namespace definitions][1].

{{< highlight shell >}}
curl -X GET \
http://127.0.0.1:8080/api/core/v2/namespaces \
-H "Authorization: Bearer $SENSU_TOKEN" \
[
  {
    "name": "default"
  },
  {
    "name": "development"
  }
]
{{< /highlight >}}

#### API Specification {#namespaces-get-specification}

/namespaces (GET)  | 
---------------|------
description    | Returns the list of namespaces.
example url    | http://hostname:8080/api/core/v2/namespaces
pagination     | This endpoint supports pagination using the `limit` and `continue` query parameters. See the [API overview][2] for details.
response type  | Array
response codes | <ul><li>**Success**: 200 (OK)</li><li>**Error**: 500 (Internal Server Error)</li></ul>
output         | {{< highlight shell >}}
[
  {
    "name": "default"
  },
  {
    "name": "development"
  }
]
{{< /highlight >}}

### `/namespaces` (POST)

The `/namespaces` API endpoint provides HTTP POST access to create Sensu namespaces.

#### EXAMPLE {#namespaces-post-example}

In the following example, an HTTP POST request is submitted to the `/namespaces` API endpoint to create the namespace `development`.
The request returns a successful HTTP `201 Created` response.

{{< highlight shell >}}
curl -X POST \
-H "Authorization: Bearer $SENSU_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
  "name": "development"
}' \
http://127.0.0.1:8080/api/core/v2/namespaces/default/namespaces

HTTP/1.1 201 Created
{{< /highlight >}}

#### API Specification {#namespaces-post-specification}

/namespaces (POST) | 
----------------|------
description     | Creates a Sensu namespace.
example URL     | http://hostname:8080/api/core/v2/namespaces
payload         | {{< highlight shell >}}
{
  "name": "development"
}
{{< /highlight >}}
response codes  | <ul><li>**Success**: 201 (Created)</li><li>**Malformed**: 400 (Bad Request)</li><li>**Error**: 500 (Internal Server Error)</li></ul>

## The `/namespaces/:namespace` API endpoint {#the-namespacesnamespace-api-endpoint}

### `/namespaces/:namespace` (PUT) {#namespacesnamespace-put}

The `/namespaces/:namespace` API endpoint provides HTTP PUT access to create or update specific Sensu namespaces, by namespace name.

#### EXAMPLE {#namespacesnamespace-put-example}

In the following example, an HTTP PUT request is submitted to the `/namespaces/:namespace` API endpoint to create the namespace `development`.
The request returns a successful HTTP `201 Created` response.

{{< highlight shell >}}
curl -X PUT \
-H "Authorization: Bearer $SENSU_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
  "name": "development"
}' \
http://127.0.0.1:8080/api/core/v2/namespaces/default/namespaces/development

HTTP/1.1 201 Created
{{< /highlight >}}

#### API Specification {#namespacesnamespace-put-specification}

/namespaces/:namespace (PUT) | 
----------------|------
description     | Creates or updates a Sensu namespace.
example URL     | http://hostname:8080/api/core/v2/namespaces/development
payload         | {{< highlight shell >}}
{
  "name": "development"
}
{{< /highlight >}}
response codes  | <ul><li>**Success**: 201 (Created)</li><li>**Malformed**: 400 (Bad Request)</li><li>**Error**: 500 (Internal Server Error)</li></ul>

### `/namespaces/:namespace` (DELETE) {#namespacesnamespace-delete}

The `/namespaces/:namespace` API endpoint provides HTTP DELETE access to delete a namespace from Sensu (specified by the namespace name).

#### EXAMPLE {#namespacesnamespace-delete-example}

The following example shows a request to the `/namespaces/:namespace` API endpoint to delete the namespace `development`, resulting in a successful HTTP `204 No Content` response.

{{< highlight shell >}}
curl -X DELETE \
http://127.0.0.1:8080/api/core/v2/namespaces/development \
-H "Authorization: Bearer $SENSU_TOKEN" \

HTTP/1.1 204 No Content
{{< /highlight >}}

#### API Specification {#namespacesnamespace-delete-specification}

/namespaces/:namespace (DELETE) | 
--------------------------|------
description               | Removes the specified namespace from Sensu.
example url               | http://hostname:8080/api/core/v2/namespaces/development
response codes            | <ul><li>**Success**: 204 (No Content)</li><li>**Missing**: 404 (Not Found)</li><li>**Error**: 500 (Internal Server Error)</li></ul>

## The `/user-namespaces` API endpoint {#the-user-namespaces-api-endpoint}

### `/user-namespaces` (GET)

The `/user-namespaces` API endpoint provides HTTP GET access to the namespaces the user has access to.

#### EXAMPLE {#user-namespaces-get-example}

The following example demonstrates a request to the `/user-namespaces` API endpoint, resulting in a JSON array that contains the namespaces the user has access to.

{{< highlight shell >}}
curl -X GET \
http://1172.16.17.32:8080/api/enterprise/user-namespaces \
-H "Authorization: Bearer $SENSU_TOKEN" \

[
  {
    "name": "default"
  },
  {
    "name": "development"
  }
]
{{< /highlight >}}

#### API Specification {#namespaces-get-specification}

/user-namespaces (GET)  | 
---------------|------
description    | Returns the list of namespaces a user has access to.
example url    | http://hostname:8080/api/enterprise/user-namespaces
response type  | Array
response codes | <ul><li>**Success**: 200 (OK)</li><li>**Error**: 500 (Internal Server Error)</li></ul>
output         | {{< highlight shell >}}
[
  {
    "name": "default"
  },
  {
    "name": "development"
  }
]
{{< /highlight >}}
{'fraction_non_alphanumeric': 0.17574562484594528, 'fraction_numerical': 0.02218387971407444, 'mean_word_length': 3.824415378517638, 'pattern_counts': {'":': 22, '<': 107, '<?xml version=': 0, '>': 107, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 8, 'substrings_counts': 0, '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': '4725429', 'n_tokens_mistral': 3949, 'n_tokens_neox': 3698, 'n_words': 1051}