Registry↗Dashboard↗

Definitions

Definition CRUD and lifecycle operations

20 endpoints

List definitions

List definitions with optional filtering and pagination.

Parameters

typestringquery

Filter by definition type

agentcommandworkflowpipeline
statusstringquery

Filter by lifecycle status

draftpublisheddeprecatedarchived
agentTypestringquery

Filter by agent type

validatorexecutoranalystgeneratorexplorerforecaster
domainstringquery

Filter by domain category

softwaresecuritycompliancelegalmedicalfinancialscientificcontentgeneralcareerbusinesseducationdocumentationcognitive-lens
tierstringquery

Filter by quality tier

userorgpro
visibilitystringquery

Filter by visibility level

privateunlistedpublic
authorIdstringuuidquery

Filter by author UUID

searchstringquery

Search in name, displayName, and description

isForkstringquery

Filter by fork status ("true" = only forks, "false" = only originals). Passed as a string query parameter, not a native boolean.

truefalse
authorshipTypestringquery

Filter by authorship provenance type

humanagentcollaborativeautomated
tagstringquery

Filter by tag(s). Can be repeated for multiple tags.

limitintegerquery

Maximum number of results (default 50, max 100)

Default: 50
offsetintegerquery

Number of results to skip

Default: 0
sortBystringquery

Field to sort by

namecreatedAtupdatedAtexecutionCountuniqueExecutionCount
sortOrderstringquery

Sort direction

ascdesc
Default: desc
latestOnlybooleanquery

When true, returns only the latest version per (type, name) pair. Defaults to true — omit or set to false to see all versions.

Default: true

Responses

200Paginated list of definitions
400Invalid request parameters

Response fields

dataobject
GET/api/v1/definitions
curl -X GET "https://api.uluops.ai/api/v1/definitions"
Response
{
  "data": {
    "definitions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "agent",
      "name": "...",
      "version": "...",
      "status": "draft",
      "domain": "software",
      "subdomain": "...",
      "agentType": "validator",
      "displayName": "...",
      "description": "...",
      "author": "...",
      "authorshipType": "human",
      "tags": [],
      "authorId": "550e8400-e29b-41d4-a716-446655440000",
      "orgId": "550e8400-e29b-41d4-a716-446655440000",
      "tier": "user",
      "visibility": "private",
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-01-15T10:30:00Z",
      "publishedAt": "2026-01-15T10:30:00Z",
      "executionCount": 0,
      "uniqueExecutionCount": 0,
      "forkCount": 0,
      "starCount": 0,
      "forkedFromId": "550e8400-e29b-41d4-a716-446655440000",
      "namespace": "...",
      "minSubscription": "...",
      "catalogueTier": "free",
      "releasedAt": "2026-01-15T10:30:00Z"
    }
  ],
    "total": 0,
    "limit": 0,
    "offset": 0,
    "hasMore": true
  }
}

Get a definition by org namespace

Get a definition scoped to an organization namespace. Supports `name@version` syntax. If no version specified, returns the latest published version within the org. Example: `GET /definitions/agent/@ulu-labs/code-validator`

Parameters

typerequiredstringpath

Definition type

agentcommandworkflowpipeline
orgSlugrequiredstringpath

Organization slug (without @ prefix)

namerequiredstringpath

Definition name (lowercase alphanumeric with hyphens)

includeRuntimebooleanquery
Default: true
includeYamlbooleanquery
Default: true

Responses

200The definition
404Resource not found

Response fields

dataobject
GET/api/v1/definitions/{type}/@{orgSlug}/{name}
curl -X GET "https://api.uluops.ai/api/v1/definitions/agent/@example-value/my-project"
Response
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "agent",
    "name": "...",
    "version": "...",
    "yaml": "...",
    "hash": "...",
    "status": "draft",
    "domain": "software",
    "subdomain": "...",
    "agentType": "validator",
    "displayName": "...",
    "description": "...",
    "author": "...",
    "provenance": {
    "authorshipType": "human",
    "contributors": [
    {
      "id": "...",
      "role": "author",
      "type": "human",
      "name": "...",
      "agentName": "...",
      "contributedAt": "2026-01-15T10:30:00Z"
    }
  ],
    "dialecticRounds": 0,
    "optimizationRunId": "..."
  },
    "tags": [],
    "authorId": "550e8400-e29b-41d4-a716-446655440000",
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "tier": "user",
    "visibility": "private",
    "runtimeMd": "...",
    "promptHash": "...",
    "translatorVersion": "...",
    "schemaVersion": "...",
    "executionCount": 0,
    "uniqueExecutionCount": 0,
    "forkCount": 0,
    "starCount": 0,
    "forkedFromId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-01-15T10:30:00Z",
    "publishedAt": "2026-01-15T10:30:00Z",
    "deprecatedAt": "2026-01-15T10:30:00Z"
  }
}

Get a definition

Get a definition by type and name. Supports `name@version` syntax. If no version specified, returns the latest published version.

Parameters

typerequiredstringpath

Definition type

agentcommandworkflowpipeline
namerequiredstringpath

Definition name (lowercase alphanumeric with hyphens)

includeRuntimebooleanquery

Include rendered runtime markdown in response

Default: true
includeYamlbooleanquery

Include raw YAML source in response

Default: true
includeRefsbooleanquery

Include dependency references in response

Default: false
normalizebooleanquery

Include normalized YAML in response

Default: false

Responses

200The definition
404Resource not found

Response fields

dataobject
GET/api/v1/definitions/{type}/{name}
curl -X GET "https://api.uluops.ai/api/v1/definitions/agent/my-project"
Response
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "agent",
    "name": "...",
    "version": "...",
    "yaml": "...",
    "hash": "...",
    "status": "draft",
    "domain": "software",
    "subdomain": "...",
    "agentType": "validator",
    "displayName": "...",
    "description": "...",
    "author": "...",
    "provenance": {
    "authorshipType": "human",
    "contributors": [
    {
      "id": "...",
      "role": "author",
      "type": "human",
      "name": "...",
      "agentName": "...",
      "contributedAt": "2026-01-15T10:30:00Z"
    }
  ],
    "dialecticRounds": 0,
    "optimizationRunId": "..."
  },
    "tags": [],
    "authorId": "550e8400-e29b-41d4-a716-446655440000",
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "tier": "user",
    "visibility": "private",
    "runtimeMd": "...",
    "promptHash": "...",
    "translatorVersion": "...",
    "schemaVersion": "...",
    "executionCount": 0,
    "uniqueExecutionCount": 0,
    "forkCount": 0,
    "starCount": 0,
    "forkedFromId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-01-15T10:30:00Z",
    "publishedAt": "2026-01-15T10:30:00Z",
    "deprecatedAt": "2026-01-15T10:30:00Z"
  }
}

Create a definition

Create a new definition in draft status.

Requires authentication

Parameters

typerequiredstringpath

Definition type

agentcommandworkflowpipeline
namerequiredstringpath

Definition name (lowercase alphanumeric with hyphens)

Request BodyCreateDefinitionInput

yamlrequiredstring

The YAML definition content (ADL for agents, CDL for commands)

visibilitystring

Definition visibility level

privateunlistedpublic
provenanceobjectnullable

Authorship provenance — captures the collaborative topology of who contributed to a definition, what role they played, and whether human or agent.

Responses

201Created definition
400Invalid request parameters
409Resource already exists

Response fields

dataobject
POST/api/v1/definitions/{type}/{name}
curl -X POST "https://api.uluops.ai/api/v1/definitions/agent/my-project" \
  -H "Authorization: Bearer $ULUOPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "yaml": "name: example-agent\nversion: 1.0.0"
  }'
Response
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "agent",
    "name": "...",
    "version": "...",
    "yaml": "...",
    "hash": "...",
    "status": "draft",
    "domain": "software",
    "subdomain": "...",
    "agentType": "validator",
    "displayName": "...",
    "description": "...",
    "author": "...",
    "provenance": {
    "authorshipType": "human",
    "contributors": [
    {
      "id": "...",
      "role": "author",
      "type": "human",
      "name": "...",
      "agentName": "...",
      "contributedAt": "2026-01-15T10:30:00Z"
    }
  ],
    "dialecticRounds": 0,
    "optimizationRunId": "..."
  },
    "tags": [],
    "authorId": "550e8400-e29b-41d4-a716-446655440000",
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "tier": "user",
    "visibility": "private",
    "runtimeMd": "...",
    "promptHash": "...",
    "translatorVersion": "...",
    "schemaVersion": "...",
    "executionCount": 0,
    "uniqueExecutionCount": 0,
    "forkCount": 0,
    "starCount": 0,
    "forkedFromId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-01-15T10:30:00Z",
    "publishedAt": "2026-01-15T10:30:00Z",
    "deprecatedAt": "2026-01-15T10:30:00Z"
  }
}

Update a definition

Update a draft definition. Requires `name@version` syntax. Only draft definitions can be updated.

Requires authentication

Parameters

typerequiredstringpath

Definition type

agentcommandworkflowpipeline
namerequiredstringpath

Definition name with version (name@version format)

Request BodyUpdateDefinitionInput

yamlstring

Updated YAML content

visibilitystring

Definition visibility level

privateunlistedpublic
displayNamestring
descriptionstring
domainstring

Definition domain category

softwaresecuritycompliancelegalmedicalfinancialscientificcontentgeneralcareerbusinesseducationdocumentationcognitive-lens
subdomainstring
agentTypestring

Agent archetype classification

validatorexecutoranalystgeneratorexplorerforecaster
tagsstring[]
provenanceobjectnullable

Authorship provenance — captures the collaborative topology of who contributed to a definition, what role they played, and whether human or agent.

changeSummarystring

Summary of changes made in this update

changeTypestring

Semantic version change type

majorminorpatch
tierstring

Definition tier classification

Responses

200Updated definition
400Invalid request parameters
404Resource not found

Response fields

dataobject
PUT/api/v1/definitions/{type}/{name}
curl -X PUT "https://api.uluops.ai/api/v1/definitions/agent/my-project" \
  -H "Authorization: Bearer $ULUOPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "agent",
    "name": "...",
    "version": "...",
    "yaml": "...",
    "hash": "...",
    "status": "draft",
    "domain": "software",
    "subdomain": "...",
    "agentType": "validator",
    "displayName": "...",
    "description": "...",
    "author": "...",
    "provenance": {
    "authorshipType": "human",
    "contributors": [
    {
      "id": "...",
      "role": "author",
      "type": "human",
      "name": "...",
      "agentName": "...",
      "contributedAt": "2026-01-15T10:30:00Z"
    }
  ],
    "dialecticRounds": 0,
    "optimizationRunId": "..."
  },
    "tags": [],
    "authorId": "550e8400-e29b-41d4-a716-446655440000",
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "tier": "user",
    "visibility": "private",
    "runtimeMd": "...",
    "promptHash": "...",
    "translatorVersion": "...",
    "schemaVersion": "...",
    "executionCount": 0,
    "uniqueExecutionCount": 0,
    "forkCount": 0,
    "starCount": 0,
    "forkedFromId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-01-15T10:30:00Z",
    "publishedAt": "2026-01-15T10:30:00Z",
    "deprecatedAt": "2026-01-15T10:30:00Z"
  }
}

Delete a definition

Delete a draft definition. Requires `name@version` syntax.

Requires authentication

Parameters

typerequiredstringpath

Definition type

agentcommandworkflowpipeline
namerequiredstringpath

Definition name with version (name@version format)

Responses

204Definition deleted
404Resource not found
DELETE/api/v1/definitions/{type}/{name}
curl -X DELETE "https://api.uluops.ai/api/v1/definitions/agent/my-project" \
  -H "Authorization: Bearer $ULUOPS_TOKEN"

Publish a definition

Publish a draft definition, making it immutable and resolvable. Requires `name@version` syntax. The response may include a top-level `warnings` array for non-fatal failures (translation, safety scan). When `TRANSLATION_FAILED` is present, the definition was published but `runtimeMd` is null and rendering will not work until the YAML is corrected. Empty/absent warnings indicates a clean publish.

Requires authentication

Parameters

typerequiredstringpath

Definition type

agentcommandworkflowpipeline
namerequiredstringpath

Definition name with version (name@version format)

Responses

200Published definition (possibly with non-fatal warnings)
400Invalid request parameters
404Resource not found

Response fields

dataobject
warningsPublishWarning[]
POST/api/v1/definitions/{type}/{name}/publish
curl -X POST "https://api.uluops.ai/api/v1/definitions/agent/my-project/publish" \
  -H "Authorization: Bearer $ULUOPS_TOKEN"
Response
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "agent",
    "name": "...",
    "version": "...",
    "yaml": "...",
    "hash": "...",
    "status": "draft",
    "domain": "software",
    "subdomain": "...",
    "agentType": "validator",
    "displayName": "...",
    "description": "...",
    "author": "...",
    "provenance": {
    "authorshipType": "human",
    "contributors": [
    {
      "id": "...",
      "role": "author",
      "type": "human",
      "name": "...",
      "agentName": "...",
      "contributedAt": "2026-01-15T10:30:00Z"
    }
  ],
    "dialecticRounds": 0,
    "optimizationRunId": "..."
  },
    "tags": [],
    "authorId": "550e8400-e29b-41d4-a716-446655440000",
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "tier": "user",
    "visibility": "private",
    "runtimeMd": "...",
    "promptHash": "...",
    "translatorVersion": "...",
    "schemaVersion": "...",
    "executionCount": 0,
    "uniqueExecutionCount": 0,
    "forkCount": 0,
    "starCount": 0,
    "forkedFromId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-01-15T10:30:00Z",
    "publishedAt": "2026-01-15T10:30:00Z",
    "deprecatedAt": "2026-01-15T10:30:00Z"
  },
  "warnings": [
    {
      "code": "...",
      "message": "...",
      "details": "..."
    }
  ]
}

Deprecate a definition

Mark a published definition as deprecated. Requires `name@version` syntax.

Requires authentication

Parameters

typerequiredstringpath

Definition type

agentcommandworkflowpipeline
namerequiredstringpath

Definition name with version (name@version format)

Request BodyDeprecateDefinitionInput

reasonrequiredstring

Human-readable explanation for deprecation

successorstring

Reference to successor definition in format "name" or "name@version". The type is inherited from the deprecated definition.

Pattern: ^[a-z][a-z0-9-]*(@\d+\.\d+\.\d+)?$

Responses

200Deprecated definition
400Invalid request parameters
404Resource not found

Response fields

dataobject
POST/api/v1/definitions/{type}/{name}/deprecate
curl -X POST "https://api.uluops.ai/api/v1/definitions/agent/my-project/deprecate" \
  -H "Authorization: Bearer $ULUOPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Resolved in latest commit"
  }'
Response
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "agent",
    "name": "...",
    "version": "...",
    "yaml": "...",
    "hash": "...",
    "status": "draft",
    "domain": "software",
    "subdomain": "...",
    "agentType": "validator",
    "displayName": "...",
    "description": "...",
    "author": "...",
    "provenance": {
    "authorshipType": "human",
    "contributors": [
    {
      "id": "...",
      "role": "author",
      "type": "human",
      "name": "...",
      "agentName": "...",
      "contributedAt": "2026-01-15T10:30:00Z"
    }
  ],
    "dialecticRounds": 0,
    "optimizationRunId": "..."
  },
    "tags": [],
    "authorId": "550e8400-e29b-41d4-a716-446655440000",
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "tier": "user",
    "visibility": "private",
    "runtimeMd": "...",
    "promptHash": "...",
    "translatorVersion": "...",
    "schemaVersion": "...",
    "executionCount": 0,
    "uniqueExecutionCount": 0,
    "forkCount": 0,
    "starCount": 0,
    "forkedFromId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-01-15T10:30:00Z",
    "publishedAt": "2026-01-15T10:30:00Z",
    "deprecatedAt": "2026-01-15T10:30:00Z"
  }
}

Archive a definition

Move a deprecated definition to archived state (terminal). Archived definitions are not discoverable in search/lists but remain resolvable by direct ID. Requires name@version format.

Requires authentication

Parameters

typerequiredstringpath

Definition type

agentcommandworkflowpipeline
namerequiredstringpath

Definition name with version (name@version format)

Responses

200Archived definition
400Invalid request parameters
404Resource not found
409Definition is not in deprecated state

Response fields

dataobject
POST/api/v1/definitions/{type}/{name}/archive
curl -X POST "https://api.uluops.ai/api/v1/definitions/agent/my-project/archive" \
  -H "Authorization: Bearer $ULUOPS_TOKEN"
Response
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "agent",
    "name": "...",
    "version": "...",
    "yaml": "...",
    "hash": "...",
    "status": "draft",
    "domain": "software",
    "subdomain": "...",
    "agentType": "validator",
    "displayName": "...",
    "description": "...",
    "author": "...",
    "provenance": {
    "authorshipType": "human",
    "contributors": [
    {
      "id": "...",
      "role": "author",
      "type": "human",
      "name": "...",
      "agentName": "...",
      "contributedAt": "2026-01-15T10:30:00Z"
    }
  ],
    "dialecticRounds": 0,
    "optimizationRunId": "..."
  },
    "tags": [],
    "authorId": "550e8400-e29b-41d4-a716-446655440000",
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "tier": "user",
    "visibility": "private",
    "runtimeMd": "...",
    "promptHash": "...",
    "translatorVersion": "...",
    "schemaVersion": "...",
    "executionCount": 0,
    "uniqueExecutionCount": 0,
    "forkCount": 0,
    "starCount": 0,
    "forkedFromId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-01-15T10:30:00Z",
    "publishedAt": "2026-01-15T10:30:00Z",
    "deprecatedAt": "2026-01-15T10:30:00Z"
  }
}

Get translator version

Returns the current version of the YAML-to-Markdown translator.

Responses

200Translator version

Response fields

dataobject
GET/api/v1/definitions/translation/version
curl -X GET "https://api.uluops.ai/api/v1/definitions/translation/version"
Response
{
  "data": {
    "translatorVersion": "..."
  }
}

Retranslate a definition

Retranslate a definition using the latest translator version. Updates runtimeMd without changing the yaml content. Requires `name@version` syntax.

Requires authentication

Parameters

typerequiredstringpath

Definition type

agentcommandworkflowpipeline
namerequiredstringpath

Definition name with version (name@version format)

Responses

200Retranslation result
400Invalid request parameters
404Resource not found

Response fields

dataobject
POST/api/v1/definitions/{type}/{name}/retranslate
curl -X POST "https://api.uluops.ai/api/v1/definitions/agent/my-project/retranslate" \
  -H "Authorization: Bearer $ULUOPS_TOKEN"
Response
{
  "data": {
    "type": "agent",
    "name": "...",
    "version": "...",
    "translatorVersion": "...",
    "previousTranslatorVersion": "...",
    "newVersionCreated": true,
    "newVersion": "...",
    "changes": true
  }
}

Upgrade to dual-storage format

Upgrade a legacy definition to dual-storage format (yaml + runtimeMd). Creates a new major version with the translated runtime markdown.

Requires authentication

Parameters

typerequiredstringpath

Definition type

agentcommandworkflowpipeline
namerequiredstringpath

Definition name (lowercase alphanumeric with hyphens)

Request Body

yamlrequiredstring

YAML content to upgrade

Responses

201Upgrade result
400Invalid request parameters
404Resource not found

Response fields

dataobject
POST/api/v1/definitions/{type}/{name}/upgrade
curl -X POST "https://api.uluops.ai/api/v1/definitions/agent/my-project/upgrade" \
  -H "Authorization: Bearer $ULUOPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "yaml": "name: example-agent\nversion: 1.0.0"
  }'
Response
{
  "data": {
    "type": "agent",
    "name": "...",
    "version": "...",
    "previousVersion": "...",
    "translatorVersion": "...",
    "upgraded": true
  }
}

Fork a definition

Create a fork of a definition under the authenticated user's ownership. Supports `name@version` syntax; if no version specified, forks the latest published version.

Requires authentication

Parameters

typerequiredstringpath

Definition type

agentcommandworkflowpipeline
namerequiredstringpath

Definition name (lowercase alphanumeric with hyphens)

Request BodyForkDefinitionInput

namerequiredstring

Name for the forked definition

Pattern: ^[a-z][a-z0-9-]*$
visibilitystring

Definition visibility level

privateunlistedpublic
displayNamestring

Optional display name override

descriptionstring

Optional description override

Responses

201Fork created successfully
400Invalid request parameters
403Cannot fork this definition (pro tier, private, etc.)
404Resource not found
409Resource already exists

Response fields

dataobject
POST/api/v1/definitions/{type}/{name}/fork
curl -X POST "https://api.uluops.ai/api/v1/definitions/agent/my-project/fork" \
  -H "Authorization: Bearer $ULUOPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-project"
  }'
Response
{
  "data": {
    "definition": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "agent",
    "name": "...",
    "version": "...",
    "yaml": "...",
    "hash": "...",
    "status": "draft",
    "domain": "software",
    "subdomain": "...",
    "agentType": "validator",
    "displayName": "...",
    "description": "...",
    "author": "...",
    "provenance": {
    "authorshipType": "human",
    "contributors": [
    {
      "id": "...",
      "role": "author",
      "type": "human",
      "name": "...",
      "agentName": "...",
      "contributedAt": "2026-01-15T10:30:00Z"
    }
  ],
    "dialecticRounds": 0,
    "optimizationRunId": "..."
  },
    "tags": [],
    "authorId": "550e8400-e29b-41d4-a716-446655440000",
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "tier": "user",
    "visibility": "private",
    "runtimeMd": "...",
    "promptHash": "...",
    "translatorVersion": "...",
    "schemaVersion": "...",
    "executionCount": 0,
    "uniqueExecutionCount": 0,
    "forkCount": 0,
    "starCount": 0,
    "forkedFromId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-01-15T10:30:00Z",
    "publishedAt": "2026-01-15T10:30:00Z",
    "deprecatedAt": "2026-01-15T10:30:00Z"
  },
    "fork": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "definitionId": "550e8400-e29b-41d4-a716-446655440000",
    "sourceDefinitionId": "550e8400-e29b-41d4-a716-446655440000",
    "forkedAt": "2026-01-15T10:30:00Z"
  },
    "source": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "agent",
    "name": "...",
    "version": "...",
    "authorId": "550e8400-e29b-41d4-a716-446655440000",
    "orgId": "550e8400-e29b-41d4-a716-446655440000"
  },
    "warnings": []
  }
}

Check if definition can be forked

Check if a definition can be forked by the current user. Returns reasons if forking is not allowed.

Parameters

typerequiredstringpath

Definition type

agentcommandworkflowpipeline
namerequiredstringpath

Definition name (lowercase alphanumeric with hyphens)

Responses

200Forkability check result
404Resource not found

Response fields

dataobject
GET/api/v1/definitions/{type}/{name}/forkable
curl -X GET "https://api.uluops.ai/api/v1/definitions/agent/my-project/forkable"
Response
{
  "data": {
    "canFork": true,
    "reason": "..."
  }
}

Get fork lineage

Get the fork lineage for a definition. Shows the source definition if this is a fork.

Parameters

typerequiredstringpath

Definition type

agentcommandworkflowpipeline
namerequiredstringpath

Definition name (lowercase alphanumeric with hyphens)

Responses

200Fork lineage
404Resource not found

Response fields

dataobject
GET/api/v1/definitions/{type}/{name}/lineage
curl -X GET "https://api.uluops.ai/api/v1/definitions/agent/my-project/lineage"
Response
{
  "data": {
    "isFork": true,
    "fork": "...",
    "source": "..."
  }
}

List forks of a definition

List all definitions that were forked from this one.

Parameters

typerequiredstringpath

Definition type

agentcommandworkflowpipeline
namerequiredstringpath

Definition name (lowercase alphanumeric with hyphens)

Responses

200List of forks
404Resource not found

Response fields

dataobject
GET/api/v1/definitions/{type}/{name}/forks
curl -X GET "https://api.uluops.ai/api/v1/definitions/agent/my-project/forks"
Response
{
  "data": {
    "forks": [
    {
      "fork": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "definitionId": "550e8400-e29b-41d4-a716-446655440000",
    "sourceDefinitionId": "550e8400-e29b-41d4-a716-446655440000",
    "forkedAt": "2026-01-15T10:30:00Z"
  },
      "definition": "..."
    }
  ],
    "totalForks": 0
  }
}

Get dependency graph

Get the full dependency graph for a definition. Returns both a tree structure and a flat list of all dependencies.

Parameters

typerequiredstringpath

Definition type

agentcommandworkflowpipeline
namerequiredstringpath

Definition name (lowercase alphanumeric with hyphens)

maxDepthintegerquery

Maximum depth to traverse. If omitted, traverses the full dependency tree up to the system limit.

Default: 10

Responses

200Dependency graph
404Resource not found

Response fields

dataobject
GET/api/v1/definitions/{type}/{name}/dependencies
curl -X GET "https://api.uluops.ai/api/v1/definitions/agent/my-project/dependencies"
Response
{
  "data": {
    "definition": {
    "type": "agent",
    "name": "...",
    "version": "..."
  },
    "graph": {
    "type": "agent",
    "name": "...",
    "version": "...",
    "dependencies": [
    {
      "type": "agent",
      "name": "...",
      "version": "...",
      "dependencies": [
    {
      "type": "agent",
      "name": "...",
      "version": "...",
      "dependencies": [
    {
      "type": "agent",
      "name": "...",
      "version": "...",
      "dependencies": []
    }
  ]
    }
  ]
    }
  ]
  },
    "flat": [
    {
      "type": "agent",
      "name": "...",
      "version": "..."
    }
  ],
    "totalCount": 0,
    "maxDepth": 0
  }
}

Get dependents

Get all definitions that depend on this one.

Parameters

typerequiredstringpath

Definition type

agentcommandworkflowpipeline
namerequiredstringpath

Definition name (lowercase alphanumeric with hyphens)

Responses

200List of dependents
404Resource not found

Response fields

dataobject
GET/api/v1/definitions/{type}/{name}/dependents
curl -X GET "https://api.uluops.ai/api/v1/definitions/agent/my-project/dependents"
Response
{
  "data": {
    "definition": {
    "type": "agent",
    "name": "...",
    "version": "..."
  },
    "dependents": [
    {
      "type": "agent",
      "name": "...",
      "version": "..."
    }
  ],
    "totalCount": 0
  }
}

Get execution statistics

Get execution count statistics for a definition.

Parameters

typerequiredstringpath

Definition type

agentcommandworkflowpipeline
namerequiredstringpath

Definition name (lowercase alphanumeric with hyphens)

windowintegerquery

Time window in minutes for recent count (default 60, max 43200)

Default: 60
includearrayquery

Additional breakdowns to include in the response

timeBucketstringquery

Time bucket granularity for byTime breakdown

hourday
Default: hour

Responses

200Execution statistics
404Resource not found

Response fields

dataobject
GET/api/v1/definitions/{type}/{name}/executions
curl -X GET "https://api.uluops.ai/api/v1/definitions/agent/my-project/executions"
Response
{
  "data": {
    "totalCount": 0,
    "recentCount": 0,
    "windowMinutes": 0
  }
}

Record an execution (admin)

Record a definition execution. Supports idempotency via runId. If runId is provided and already recorded, returns 200 instead of 201. Requires admin role — execution recording is handled automatically by the platform.

Requires authentication

Parameters

typerequiredstringpath

Definition type

agentcommandworkflowpipeline
namerequiredstringpath

Definition name (lowercase alphanumeric with hyphens)

Request BodyRecordExecutionInput

sourcerequiredstring

Source of execution (e.g., 'sdk', 'cli', 'api')

runIdstring

Unique run ID for idempotency

Responses

200Duplicate execution (idempotent)
201Execution recorded
404Resource not found
429Rate limit exceeded for this definition

Response fields

dataobject
POST/api/v1/definitions/{type}/{name}/executions
curl -X POST "https://api.uluops.ai/api/v1/definitions/agent/my-project/executions" \
  -H "Authorization: Bearer $ULUOPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "example-value"
  }'
Response
{
  "data": {
    "recorded": true,
    "duplicate": true,
    "definition": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "agent",
    "name": "...",
    "version": "..."
  },
    "executionCount": 0
  }
}