> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apinizer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create API Proxy Group

> Creates a new API Proxy Group. API Proxy Groups allow you to group multiple API Proxies together and manage them as a single unit with shared client routes, CORS settings, and cache settings.

## Endpoint

```plaintext theme={null}
POST /apiops/projects/{projectName}/apiProxyGroups/
```

## Authentication

Requires a Personal API Access Token.

### Header

```plaintext theme={null}
Authorization: Bearer YOUR_TOKEN
```

## Request

### Headers

| Header        | Value            | Required |
| ------------- | ---------------- | -------- |
| Authorization | Bearer {token}   | Yes      |
| Content-Type  | application/json | Yes      |

### Path Parameters

| Parameter   | Type   | Required | Description  |
| ----------- | ------ | -------- | ------------ |
| projectName | string | Yes      | Project name |

### Request Body

#### Full JSON Body Example - Basic API Proxy Group

```json theme={null}
{
  "name": "PaymentAPIGroup",
  "description": "Payment API Group",
  "clientRoute": {
    "relativePathList": [
      "/api/v1/payment"
    ],
    "methodList": ["GET", "POST", "PUT", "DELETE"],
    "hostList": null,
    "headerList": null,
    "bufferRequest": true,
    "bufferResponse": true
  }
}
```

#### Full JSON Body Example - API Proxy Group with Host Filtering

```json theme={null}
{
  "name": "RestrictedAPIGroup",
  "description": "Restricted API Group",
  "clientRoute": {
    "relativePathList": [
      "/api/v1/restricted"
    ],
    "methodList": ["GET", "POST"],
    "hostList": [
      "api.example.com",
      "api-staging.example.com"
    ],
    "headerList": null,
    "bufferRequest": true,
    "bufferResponse": true
  }
}
```

#### Full JSON Body Example - API Proxy Group with Header-Based Routing

```json theme={null}
{
  "name": "VersionedAPIGroup",
  "description": "Versioned API Group",
  "clientRoute": {
    "relativePathList": [
      "/api/v1"
    ],
    "methodList": ["ALL"],
    "hostList": null,
    "headerList": [
      {
        "name": "X-API-Version",
        "value": "v1"
      }
    ],
    "bufferRequest": true,
    "bufferResponse": true
  }
}
```

#### Request Body Fields

| Field           | Type   | Required | Default | Description                                                                                                                        |
| --------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| name            | string | Yes      | -       | API Proxy Group name (unique identifier)                                                                                           |
| description     | string | No       | -       | API Proxy Group description                                                                                                        |
| clientRoute     | object | Yes      | -       | Client route configuration. See [Client Route Object](#client-route-object-clientroute)                                            |
| environmentName | string | No       | -       | Environment name to deploy after creation. If provided, the API Proxy Group is automatically deployed to the specified environment |

### Client Route Object (clientRoute)

| Field            | Type           | Required | Default | Description                                                                                    |
| ---------------- | -------------- | -------- | ------- | ---------------------------------------------------------------------------------------------- |
| relativePathList | array\[string] | Yes      | -       | List of relative paths to match. Must have at least one path, and first path must not be empty |
| methodList       | array\[string] | No       | null    | List of HTTP methods to match. See [EnumHttpRequestMethod](#enumhttprequestmethod-methodlist)  |
| hostList         | array\[string] | No       | null    | List of host names to match                                                                    |
| headerList       | array\[object] | No       | null    | List of headers to match. See [Header Object](#header-object-headerlist)                       |
| bufferRequest    | boolean        | No       | true    | Buffer request body                                                                            |
| bufferResponse   | boolean        | No       | true    | Buffer response body                                                                           |

### EnumHttpRequestMethod (methodList)

* `GET` - HTTP GET method
* `POST` - HTTP POST method
* `PUT` - HTTP PUT method
* `HEAD` - HTTP HEAD method
* `OPTIONS` - HTTP OPTIONS method
* `DELETE` - HTTP DELETE method
* `PATCH` - HTTP PATCH method
* `TRACE` - HTTP TRACE method
* `ALL` - All HTTP methods

### Header Object (headerList)

| Field | Type   | Required | Description                    |
| ----- | ------ | -------- | ------------------------------ |
| name  | string | Yes      | Header name (case-insensitive) |
| value | string | Yes      | Header value to match          |

### Notes

* `name` must be unique within the project
* `clientRoute.relativePathList` must have at least one path
* First path in `relativePathList` must not be empty
* At least one route configuration (path, host, header, or method) must be provided
* Paths must be at least 2 characters long

## Response

### Success Response (200 OK)

Without `environmentName`:

```json theme={null}
{
  "success": true
}
```

With `environmentName` (includes deployment result):

```json theme={null}
{
  "success": true,
  "deploymentResult": {
    "success": true,
    "responseTime": 150,
    "detailList": [
      {
        "envName": "production",
        "podName": "worker-abc123",
        "podIp": "10.0.0.1",
        "success": true,
        "responseTime": 150
      }
    ]
  }
}
```

### Error Response (400 Bad Request)

```json theme={null}
{
  "error": "bad_request",
  "error_description": "name value can not be empty!"
}
```

or

```json theme={null}
{
  "error": "bad_request",
  "error_description": "clientRoute value can not be empty!"
}
```

or

```json theme={null}
{
  "error": "bad_request",
  "error_description": "clientRoute value needs at least one relativePath!"
}
```

or

```json theme={null}
{
  "error": "bad_request",
  "error_description": "relativePath value in clientRoute object can not be empty!"
}
```

or

```json theme={null}
{
  "error": "bad_request",
  "error_description": "ApiProxyGroup: (PaymentAPIGroup) is already created! If you want to udate it use update endpoint!"
}
```

#### Common Causes

* Missing required fields (`name`, `clientRoute`)
* Empty `relativePathList` or empty first path
* API Proxy Group name already exists
* Invalid client route configuration

## cURL Example

### Example 1: Create Basic API Proxy Group

```bash theme={null}
curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxyGroups/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PaymentAPIGroup",
    "description": "Payment API Group",
    "clientRoute": {
      "relativePathList": [
        "/api/v1/payment"
      ],
      "methodList": ["GET", "POST", "PUT", "DELETE"],
      "bufferRequest": true,
      "bufferResponse": true
    }
  }'
```

### Example 2: Create API Proxy Group with Automatic Deployment

```bash theme={null}
curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxyGroups/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PaymentAPIGroup",
    "description": "Payment API Group",
    "environmentName": "production",
    "clientRoute": {
      "relativePathList": [
        "/api/v1/payment"
      ],
      "methodList": ["GET", "POST", "PUT", "DELETE"],
      "bufferRequest": true,
      "bufferResponse": true
    }
  }'
```

### Example 3: Create API Proxy Group with Host Filtering

```bash theme={null}
curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxyGroups/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "RestrictedAPIGroup",
    "description": "Restricted API Group",
    "clientRoute": {
      "relativePathList": [
        "/api/v1/restricted"
      ],
      "methodList": ["GET", "POST"],
      "hostList": [
        "api.example.com"
      ],
      "bufferRequest": true,
      "bufferResponse": true
    }
  }'
```

## Notes and Warnings

* **Name Uniqueness**:
  * API Proxy Group name must be unique within the project
  * If name already exists, creation will fail

* **Client Route**:
  * Client route is required
  * Must have at least one relative path
  * First path must not be empty
  * Paths must be at least 2 characters long

* **Route Matching**:
  * Route matching uses AND logic
  * All specified conditions must match

## Permissions

* User must have **`API_MANAGEMENT` + `MANAGE`** permission in the project

* If `environmentName` is provided, user must also have **`API_MANAGEMENT` + `DEPLOY_UNDEPLOY`** permission

* **Default Settings**:
  * CORS settings, cache settings, and error templates are created with defaults
  * Can be configured after creation

## Related Documentation

* [List API Proxy Groups](/api-reference/api-proxy-groups/crud/list-api-proxy-groups) - List all API Proxy Groups
* [Update API Proxy Group](/api-reference/api-proxy-groups/crud/update-api-proxy-group) - Update an API Proxy Group
* [Add API Proxy to Group](/api-reference/api-proxy-groups/api-proxies/add-api-proxy-to-group) - Add API Proxies to group