Logic API

Logic definitions encode your organization's metrics, terms, and rules. This page documents all logic-related endpoints.

The Definition Object

json

1{
2  "id": "def_abc123def456",
3  "name": "High-risk contract",
4  "definition_type": "rule",
5  "definition": "A contract with liability exceeding $1M OR containing a termination amendment",
6  "datastore_id": null,
7  "version": 3,
8  "created_at": "2024-01-15T10:30:00Z",
9  "updated_at": "2024-01-20T14:00:00Z",
10  "created_by": "user_xyz789"
11}

Attributes

| Field | Type | Description | |-------|------|-------------| | id | string | Unique identifier for the definition | | name | string | Display name of the definition | | definition_type | string | Type: metric, term, or rule | | definition | string | The full definition content | | datastore_id | string | Associated datastore ID, or null for workspace-level | | version | integer | Current version number | | created_at | string | ISO 8601 timestamp of creation | | updated_at | string | ISO 8601 timestamp of last update | | created_by | string | User ID who created the definition |

Definition Types

| Type | Description | Example | |------|-------------|---------| | metric | Mathematical calculations and KPIs | "MRR = sum of monthly subscription values" | | term | What concepts mean | "Enterprise = org with >500 employees" | | rule | How to behave or categorize | "High-risk = liability > $1M OR termination clause" |

List Definitions

GET/v1/definitions

Returns a list of all definitions in your workspace

Query Parameters

| Parameter | Type | Description | |-----------|------|-------------| | limit | integer | Number of definitions to return (1-100, default 20) | | cursor | string | Pagination cursor from previous response | | type | string | Filter by type (metric, term, rule) | | datastore_id | string | Filter by datastore (use null for workspace-level) |

Response

json

1{
2  "data": [
3    {
4      "id": "def_abc123",
5      "name": "High-risk contract",
6      "definition_type": "rule",
7      "definition": "Liability > $1M OR termination amendment",
8      "datastore_id": null,
9      "version": 2,
10      "created_at": "2024-01-15T10:30:00Z"
11    }
12  ],
13  "has_more": false,
14  "next_cursor": null
15}

Example

bash

1curl https://api.orka.ai/v1/definitions?type=rule \
2  -H "Authorization: Bearer sk_your_api_key"

Create Definition

POST/v1/definitions

Creates a new definition

Request Body

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Display name (1-100 characters) | | definition_type | string | Yes | Type: metric, term, or rule | | definition | string | Yes | The full definition content | | datastore_id | string | No | Associate with a specific datastore |

Example Request

bash

1curl -X POST https://api.orka.ai/v1/definitions \
2  -H "Authorization: Bearer sk_your_api_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "Strategic account",
6    "definition_type": "term",
7    "definition": "A customer with ARR greater than $100K or identified as having significant growth potential"
8  }'

Response

json

1{
2  "id": "def_new123",
3  "name": "Strategic account",
4  "definition_type": "term",
5  "definition": "A customer with ARR greater than $100K or identified as having significant growth potential",
6  "datastore_id": null,
7  "version": 1,
8  "created_at": "2024-01-15T12:00:00Z",
9  "updated_at": "2024-01-15T12:00:00Z",
10  "created_by": "user_xyz789"
11}

Get Definition

GET/v1/definitions/:id

Retrieves a specific definition by ID

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The definition ID (e.g., def_abc123) |

Example

bash

1curl https://api.orka.ai/v1/definitions/def_abc123 \
2  -H "Authorization: Bearer sk_your_api_key"

Response

Returns the full definition object (see The Definition Object).

Update Definition

PUT/v1/definitions/:id

Updates an existing definition

Updating a definition creates a new version. The previous version is preserved in the version history.

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The definition ID to update |

Request Body

| Field | Type | Description | |-------|------|-------------| | name | string | New display name | | definition | string | New definition content |

The definition_type cannot be changed after creation. Create a new definition if you need a different type.

Example

bash

1curl -X PUT https://api.orka.ai/v1/definitions/def_abc123 \
2  -H "Authorization: Bearer sk_your_api_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "definition": "A contract with liability exceeding $1M OR containing a termination amendment OR payment terms greater than 90 days"
6  }'

Response

json

1{
2  "id": "def_abc123",
3  "name": "High-risk contract",
4  "definition_type": "rule",
5  "definition": "A contract with liability exceeding $1M OR containing a termination amendment OR payment terms greater than 90 days",
6  "datastore_id": null,
7  "version": 3,
8  "created_at": "2024-01-15T10:30:00Z",
9  "updated_at": "2024-01-20T14:00:00Z"
10}

Delete Definition

DELETE/v1/definitions/:id

Permanently deletes a definition

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The definition ID to delete |

Deleting a definition is permanent. All version history will also be deleted.

Example

bash

1curl -X DELETE https://api.orka.ai/v1/definitions/def_abc123 \
2  -H "Authorization: Bearer sk_your_api_key"

Response

json

1{
2  "id": "def_abc123",
3  "deleted": true
4}

Get Version History

GET/v1/definitions/:id/versions

Retrieves the version history of a definition

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The definition ID |

Example

bash

1curl https://api.orka.ai/v1/definitions/def_abc123/versions \
2  -H "Authorization: Bearer sk_your_api_key"

Response

json

1{
2  "data": [
3    {
4      "version": 3,
5      "definition": "Liability > $1M OR termination amendment OR payment > 90 days",
6      "updated_at": "2024-01-20T14:00:00Z",
7      "updated_by": "user_xyz789"
8    },
9    {
10      "version": 2,
11      "definition": "Liability > $1M OR termination amendment",
12      "updated_at": "2024-01-18T10:00:00Z",
13      "updated_by": "user_xyz789"
14    },
15    {
16      "version": 1,
17      "definition": "Liability > $1M",
18      "updated_at": "2024-01-15T10:30:00Z",
19      "updated_by": "user_xyz789"
20    }
21  ]
22}

Revert to Version

POST/v1/definitions/:id/revert

Reverts a definition to a previous version

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The definition ID |

Request Body

| Field | Type | Required | Description | |-------|------|----------|-------------| | version | integer | Yes | The version number to revert to |

Example

bash

1curl -X POST https://api.orka.ai/v1/definitions/def_abc123/revert \
2  -H "Authorization: Bearer sk_your_api_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "version": 2
6  }'

Response

Returns the definition with content from the specified version. A new version is created (the revert itself is versioned).

json

1{
2  "id": "def_abc123",
3  "name": "High-risk contract",
4  "definition_type": "rule",
5  "definition": "Liability > $1M OR termination amendment",
6  "version": 4,
7  "reverted_from": 2,
8  "updated_at": "2024-01-21T09:00:00Z"
9}