Managing Definitions

Once a definition is deployed, you can retrieve, list, update, delete, and copy it across spaces using the definition management API.

All endpoints require the five standard headers. All IDs are ULIDs.

---

Endpoint Summary

Action	Method	Endpoint
Deploy	POST	/minimal/rest/definition/v1
Get by ID	GET	/minimal/rest/definition/v1?definition_id=
List all	GET	/minimal/rest/definition/v1/list
List by method	GET	/minimal/rest/definition/v1/list?method=
Update	PUT	/minimal/rest/definition/v1
Delete	DELETE	/minimal/rest/definition/v1?uri=&method=&version=
Copy to space	PUT	/minimal/rest/definition/v1/space/copy

---

Deploy a Definition (POST)

Creates a new Custom API definition. Returns a definition_id on success.

POST /minimal/rest/definition/v1

Headers

Header	Required
X-Org-Id	✅
X-Project-Id	✅
X-Space-Id	✅
X-User-Id	✅
X-User-Roles	✅ — must include admin or power
Content-Type	✅ — application/x-yaml

curl -X POST '/minimal/rest/definition/v1' \
  -H 'X-Org-Id: 01KC11784DW133S3THR7JTQNQ1' \
  -H 'X-Project-Id: 01KC11KZ6VDMMKJZ4YWQYKYZ6Z' \
  -H 'X-Space-Id: 01KBY3K97GMAJFBQ0PP7158NZH' \
  -H 'X-User-Id: 01KBY3K9NDC5XW523M2V1Z0373' \
  -H 'X-User-Roles: admin' \
  -H 'Content-Type: application/x-yaml' \
  --data-binary @definition.yaml

Response

Returns the registered definition_id as a ULID:

{
  "definition_id": "01KCK434ADF8VGC9DQNJTKZPTD"
}

Save this ID — you'll need it to retrieve or reference this definition later.

---

Get a Definition

Retrieve a single definition by its definition_id.

GET /minimal/rest/definition/v1?definition_id={definition_id}

curl '/minimal/rest/definition/v1?definition_id=01KCK434ADF8VGC9DQNJTKZPTD' \
  -H 'X-Org-Id: 01KC11784DW133S3THR7JTQNQ1' \
  -H 'X-Project-Id: 01KC11KZ6VDMMKJZ4YWQYKYZ6Z' \
  -H 'X-Space-Id: 01KBY3K97GMAJFBQ0PP7158NZH' \
  -H 'X-User-Id: 01KBY3K9NDC5XW523M2V1Z0373' \
  -H 'X-User-Roles: admin'

---

List All Definitions

Retrieve all definitions in the current space.

GET /minimal/rest/definition/v1/list

curl '/minimal/rest/definition/v1/list' \
  -H 'X-Org-Id: 01KC11784DW133S3THR7JTQNQ1' \
  -H 'X-Project-Id: 01KC11KZ6VDMMKJZ4YWQYKYZ6Z' \
  -H 'X-Space-Id: 01KBY3K97GMAJFBQ0PP7158NZH' \
  -H 'X-User-Id: 01KBY3K9NDC5XW523M2V1Z0373' \
  -H 'X-User-Roles: admin'

---

List by Method

Filter definitions by HTTP method.

GET /minimal/rest/definition/v1/list?method={method}

Value	Returns
get	All GET definitions
post	All POST definitions
put	All PUT definitions
patch	All PATCH definitions
delete	All DELETE definitions

curl '/minimal/rest/definition/v1/list?method=get' \
  -H 'X-Org-Id: 01KC11784DW133S3THR7JTQNQ1' \
  -H 'X-Project-Id: 01KC11KZ6VDMMKJZ4YWQYKYZ6Z' \
  -H 'X-Space-Id: 01KBY3K97GMAJFBQ0PP7158NZH' \
  -H 'X-User-Id: 01KBY3K9NDC5XW523M2V1Z0373' \
  -H 'X-User-Roles: admin'

---

Update a Definition

Modify an existing definition by POSTing updated YAML. Identify the definition by its uri, method, and version.

PUT /minimal/rest/definition/v1

Headers

Header	Required
X-Org-Id	✅
X-Project-Id	✅
X-Space-Id	✅
X-User-Id	✅
X-User-Roles	✅
Content-Type	✅ — application/x-yaml

curl -X PUT '/minimal/rest/definition/v1' \
  -H 'X-Org-Id: 01KC11784DW133S3THR7JTQNQ1' \
  -H 'X-Project-Id: 01KC11KZ6VDMMKJZ4YWQYKYZ6Z' \
  -H 'X-Space-Id: 01KBY3K97GMAJFBQ0PP7158NZH' \
  -H 'X-User-Id: 01KBY3K9NDC5XW523M2V1Z0373' \
  -H 'X-User-Roles: admin' \
  -H 'Content-Type: application/x-yaml' \
  --data-binary @updated-definition.yaml

tip

Always increment http.version when updating a definition and set config.rollback_version to the previous version. See Config Reference.

---

Delete a Definition

Delete a definition by its uri, method, and version.

DELETE /minimal/rest/definition/v1?uri={uri}&method={method}&version={version}

Param	Description
uri	URL-encoded URI of the definition
method	HTTP method — get, post, put, patch, delete
version	Version to delete — e.g. 0.1

curl -X DELETE \
  '/minimal/rest/definition/v1?uri=lbl%2Fcrm%2Fusers%2Fall&method=get&version=0.1' \
  -H 'X-Org-Id: 01KC11784DW133S3THR7JTQNQ1' \
  -H 'X-Project-Id: 01KC11KZ6VDMMKJZ4YWQYKYZ6Z' \
  -H 'X-Space-Id: 01KBY3K97GMAJFBQ0PP7158NZH' \
  -H 'X-User-Id: 01KBY3K9NDC5XW523M2V1Z0373' \
  -H 'X-User-Roles: admin'

caution

Deletion is permanent. If you need to restore a deleted definition, you must redeploy the YAML from scratch.

---

Copy Definitions Across Spaces

Copy one or more definitions from the current space to a target space. Use this to promote definitions from dev → staging → production.

PUT /minimal/rest/definition/v1/space/copy

Request Body

{
  "org_id": "01KC11784DW133S3THR7JTQNQ1",
  "project_id": "01KC11KZ6VDMMKJZ4YWQYKYZ6Z",
  "space_id": "01KBY3K97GMAJFBQ0PP7158NZH",
  "target_version": "v0.1",
  "target_space_id": "01KBY3K97GMAJFBQ0PP7158NZJ",
  "user_id": "01KBY3K9NDC5XW523M2V1Z0373",
  "definition_list": [
    "01KD748G21N28VA1XWJYJB5EST",
    "01KD748YFXPNZ63E0VEE7DZ2K5",
    "01KDA54J4DT3NQF9A7BFBR21MG",
    "01KD749MRMWV42ZSZ95NT70JJD"
  ]
}

Field	Description
org_id	Source organization
project_id	Source project
space_id	Source space — where definitions currently live
target_version	Version tag to apply in the target space
target_space_id	Destination space to copy definitions into
user_id	User performing the copy
definition_list	Array of definition_id ULIDs to copy

curl -X PUT '/minimal/rest/definition/v1/space/copy' \
  -H 'X-Org-Id: 01KC11784DW133S3THR7JTQNQ1' \
  -H 'X-Project-Id: 01KC11KZ6VDMMKJZ4YWQYKYZ6Z' \
  -H 'X-Space-Id: 01KBY3K97GMAJFBQ0PP7158NZH' \
  -H 'X-User-Id: 01KBY3K9NDC5XW523M2V1Z0373' \
  -H 'X-User-Roles: admin' \
  -H 'Content-Type: application/json' \
  -d '{
    "org_id": "01KC11784DW133S3THR7JTQNQ1",
    "project_id": "01KC11KZ6VDMMKJZ4YWQYKYZ6Z",
    "space_id": "01KBY3K97GMAJFBQ0PP7158NZH",
    "target_version": "v0.1",
    "target_space_id": "01KBY3K97GMAJFBQ0PP7158NZJ",
    "user_id": "01KBY3K9NDC5XW523M2V1Z0373",
    "definition_list": [
      "01KD748G21N28VA1XWJYJB5EST",
      "01KD748YFXPNZ63E0VEE7DZ2K5",
      "01KDA54J4DT3NQF9A7BFBR21MG",
      "01KD749MRMWV42ZSZ95NT70JJD"
    ]
  }'

Typical Promotion Flow

dev space
  └── build and test definitions
        ↓
  space/copy → staging space
        ↓
  space/copy → production space

---