---
title: "POST /v2/costformation/namespace/{id}/definitions/async"
method: POST
path: "/v2/costformation/namespace/{id}/definitions/async"
tags: ["costformation-namespaces"]
---

# POST /v2/costformation/namespace/{id}/definitions/async

`POST /v2/costformation/namespace/{id}/definitions/async`

## Request

- Base URL: `https://api.cloudzero.com`
- URL: `https://api.cloudzero.com/v2/costformation/namespace/{id}/definitions/async`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/cloudzero/apis/cloudzero-api-v2-resources/docs/v2/costformation/namespace/:id/definitions/async/post.ts> (a function with typed inputs; its response is checked against the schema)

Submit an asynchronous CostFormation definition publish job for a specific namespace. Returns a job ID, initial status of `pending`, and a `poll_url` to check progress. Use the [Get a publish job](https://docs.cloudzero.com/reference/getcostformationpublishjob) endpoint to poll for completion.

## Path parameters

- `id` string, required

## Headers

- `cloudzero-idempotency-key` string
- `cloudzero-test-key` string

## Request body

- CostformationAsyncPublishRequest
  - `definitions` object, required
    - `yaml` string, required: The CostFormation definition content in YAML format.
  - `validate_only` boolean: If true, validates the definition without creating a publish job.
  - `save_draft_only` boolean: If true, saves the definition as a draft without publishing.
  - `compression` string, nullable: Optional compression format applied to the definition payload.

## Response `200`

Successful Operation

- CostformationPublishJob: Response returned when a publish job is created.
  - `job_id` string: Unique identifier for the publish job.
  - `status` string: Current status of the publish job. One of: `pending`, `in_progress`, `completed`, `failed`, `superseded`, `cancelled`.
  - `poll_url` string: URL path to poll for job status updates.

## Other responses

- `400`: Bad Request Error
- `403`: Forbidden

## Changes

- **2026-11-03** `56a692cf51b1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cloudzero/apis/cloudzero-api-v2-resources/changes/v2/costformation/namespace/:id/definitions/async/post.md)

---

[API](https://skmtc.dev/cloudzero/apis/cloudzero-api-v2-resources.md) - [All operations](https://skmtc.dev/cloudzero/apis/cloudzero-api-v2-resources/llms.txt) - [OpenAPI document](https://skmtc.dev/cloudzero/apis/cloudzero-api-v2-resources/revisions/56a692cf51b1?raw)