Formations

Get a specific formation

Returns the formation stack including its current resources.

get/v1/projects/{project_id}/formations/{formation_id}

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/formations/{formation_id}
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Path parameters

formation_idstring required

Response

Formation details

idstring

Public ID of the formation

project_idstring

Project public ID

namestring

Human-readable formation name

outputsobject nullable

Resolved output values after stack deployment. An output that resolved a credential attribute on a formation deployed before those were refused is omitted.

status'creating' | 'active' | 'updating' | 'failed' | 'deleting' | 'deleted' | 'delete_failed'

Formation status

metadataMetadataBag

Caller-owned annotations on a resource, stored as the object they were written as: the types a value was written with are the types a read returns, so a filter can ask an ordering question about a number. Unlike other body fields, keys are stored and returned verbatim in the casing supplied — they are not converted between snake_case and camelCase.

No key is reserved, and that is the point: every piece of state the platform owns lives in its own typed column, so nothing written here reaches platform state. The platform never reads the bag — it is not an IAM context, not a policy input and not part of a prompt — which is what separates it from a tag bag.

resolved_metadataobject nullable

The template's top-level metadata block after parameter (sub/param) and resource (ref) substitution at the last deploy. Null when the template declares no metadata.

resolved_parametersobject nullable

Parameter values applied at the last deploy, for auditability. no_echo parameters are masked (***). Null when the template declares no parameters.

created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "form_V1StGXR8Z5jdHi6B",
  "template": {
    "metadata": {
      "author": "John",
      "revision": 2
    }
  },
  "metadata": {
    "author": "John",
    "revision": 2
  },
  "error": {
    "code": "AI_PROVIDER_ERROR",
    "message": "Provider returned 402: insufficient credits"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.