> For the complete documentation index, see [llms.txt](https://docs.annolab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.annolab.ai/abstracts/ownership-chain-agent.md).

# Ownership Chain Agent

Launch, inspect, stop, and stream the ownership chain agent for a land abstract.

AnnoLab's ownership chain agent uses the instruments you've uploaded to an abstract, constructs an ownership chain, and predicts current ownership. When a job completes, retrieve the predicted owners with [Get Predicted Owners](/abstracts/abstracts.md#get-predicted-owners).

## Agent Job Object

| Name         | Type          | Description                                                                                                 |
| ------------ | ------------- | ----------------------------------------------------------------------------------------------------------- |
| id           | Integer       | Unique id of the agent job                                                                                  |
| abstractId   | Integer       | Abstract the job is running against                                                                         |
| agentType    | String\|null  | Agent type. Ownership chain jobs use `OwnershipChain`.                                                      |
| status       | String        | One of `Initialized`, `Launching`, `Running`, `StopRequested`, `Stopped`, `Stalled`, `Errored`, `Completed` |
| errorMessage | String\|null  | Error text when `status` is `Errored`                                                                       |
| jobData      | Object        | Job payload, including optional `progress` counts                                                           |
| createdAt    | String        | ISO formatted DateTime when the job was created                                                             |
| createdBy    | Integer\|null | User id that launched the job                                                                               |
| updatedAt    | String        | ISO formatted DateTime when the job was last updated                                                        |

`jobData.progress` may include `conveyancesAnalyzed`, `totalConveyances`, `partiesAnalyzed`, `partiesRequiringAnalysis`, and `totalParties`.

## Get latest ownership chain job

<mark style="color:blue;">`GET`</mark> `https://api.annolab.ai/v1/agents/ownership-chain/latest-job/{abstractId}`

Return the most recently updated ownership chain agent job for an abstract, or `null` if none exists. Requires an API key with "Read" permissions, and the key's user must have view access to the abstract's project.

#### Path Parameters

| Name       | Type    | Description        |
| ---------- | ------- | ------------------ |
| abstractId | integer | Id of the abstract |

#### Headers

| Name          | Type   | Description                                                                                                                                                            |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | string | <p>Where you put your api key. Getting the latest job requires a key with "Read" permissions.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

{% tabs %}
{% tab title="200 The latest job was retrieved" %}

```json
{
    "id": 501,
    "abstractId": 1842,
    "agentType": "OwnershipChain",
    "status": "Running",
    "errorMessage": null,
    "jobData": {
        "progress": {
            "conveyancesAnalyzed": 12,
            "totalConveyances": 40,
            "partiesAnalyzed": 3,
            "partiesRequiringAnalysis": 8,
            "totalParties": 8
        }
    },
    "createdAt": "2026-08-25T18:00:00.000Z",
    "createdBy": 14,
    "updatedAt": "2026-08-25T18:05:00.000Z"
}
```

{% endtab %}

{% tab title="403 Forbidden" %}

```json
{
    "message": "You do not have permission to view abstracts in that project."
}
```

{% endtab %}

{% tab title="404 The abstract was not found" %}

```json
{
    "message": "No abstract exists with the identifier <1842>"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Python" %}

```python
import requests

ANNO_LAB_API_KEY = 'XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX'

headers = {
  'Authorization': 'Api-Key '+ANNO_LAB_API_KEY,
}

url = 'https://api.annolab.ai/v1/agents/ownership-chain/latest-job/1842'

response = requests.get(url, headers=headers)

print(response.json())
```

{% endtab %}
{% endtabs %}

## Get ownership chain job

<mark style="color:blue;">`GET`</mark> `https://api.annolab.ai/v1/agents/ownership-chain/job/{jobId}`

Return the ownership chain agent job for the given id. Requires an API key with "Read" permissions, and the key's user must have view access to the job's abstract project.

#### Path Parameters

| Name  | Type    | Description         |
| ----- | ------- | ------------------- |
| jobId | integer | Id of the agent job |

#### Headers

| Name          | Type   | Description                                                                                                                                                   |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | string | <p>Where you put your api key. Getting a job requires a key with "Read" permissions.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

{% tabs %}
{% tab title="200 The job was retrieved" %}

```json
{
    "id": 501,
    "abstractId": 1842,
    "agentType": "OwnershipChain",
    "status": "Running",
    "errorMessage": null,
    "jobData": {
        "progress": {
            "conveyancesAnalyzed": 12,
            "totalConveyances": 40,
            "partiesAnalyzed": 3,
            "partiesRequiringAnalysis": 8,
            "totalParties": 8
        }
    },
    "createdAt": "2026-08-25T18:00:00.000Z",
    "createdBy": 14,
    "updatedAt": "2026-08-25T18:05:00.000Z"
}
```

{% endtab %}

{% tab title="403 Forbidden" %}

```json
{
    "message": "You do not have permission to view abstracts in that project."
}
```

{% endtab %}

{% tab title="404 The job was not found" %}

```json
{
    "message": "No agent job exists with the identifier <501>"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Python" %}

```python
import requests

ANNO_LAB_API_KEY = 'XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX'

headers = {
  'Authorization': 'Api-Key '+ANNO_LAB_API_KEY,
}

url = 'https://api.annolab.ai/v1/agents/ownership-chain/job/501'

response = requests.get(url, headers=headers)

print(response.json())
```

{% endtab %}
{% endtabs %}

## Launch ownership chain agent

<mark style="color:green;">`POST`</mark> `https://api.annolab.ai/v1/agents/ownership-chain/{abstractId}/launch`

Start an ownership chain agent job for the abstract. Requires an API key with "Write" permissions, and the key's user must be able to run model inference on the abstract's project. Returns the created [Agent Job](#agent-job-object).

#### Path Parameters

| Name       | Type    | Description        |
| ---------- | ------- | ------------------ |
| abstractId | integer | Id of the abstract |

#### Headers

| Name          | Type   | Description                                                                                                                                                          |
| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | string | <p>Where you put your api key. Launching the agent requires a key with "Write" permissions.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

{% tabs %}
{% tab title="201 The agent job was launched" %}

```json
{
    "id": 501,
    "abstractId": 1842,
    "agentType": "OwnershipChain",
    "status": "Launching",
    "errorMessage": null,
    "jobData": {},
    "createdAt": "2026-08-25T18:00:00.000Z",
    "createdBy": 14,
    "updatedAt": "2026-08-25T18:00:00.000Z"
}
```

{% endtab %}

{% tab title="403 Forbidden" %}

```json
{
    "message": "You are not permitted to run models in this project."
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Python" %}

```python
import requests

ANNO_LAB_API_KEY = 'XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX'

headers = {
  'Authorization': 'Api-Key '+ANNO_LAB_API_KEY,
}

url = 'https://api.annolab.ai/v1/agents/ownership-chain/1842/launch'

response = requests.post(url, headers=headers)

print(response.json())
```

{% endtab %}
{% endtabs %}

## Stop ownership chain agent

<mark style="color:green;">`POST`</mark> `https://api.annolab.ai/v1/agents/ownership-chain/{abstractId}/stop`

Request that the running ownership chain agent for the abstract stop. Requires an API key with "Write" permissions, and the key's user must be able to run model inference on the abstract's project.

If a running job is found, its status becomes `StopRequested` and a stop command is published to the agent. Returns the updated [Agent Job](#agent-job-object), or `null` if nothing was updated.

#### Path Parameters

| Name       | Type    | Description        |
| ---------- | ------- | ------------------ |
| abstractId | integer | Id of the abstract |

#### Headers

| Name          | Type   | Description                                                                                                                                                         |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | string | <p>Where you put your api key. Stopping the agent requires a key with "Write" permissions.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

{% tabs %}
{% tab title="Python" %}

```python
import requests

ANNO_LAB_API_KEY = 'XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX'

headers = {
  'Authorization': 'Api-Key '+ANNO_LAB_API_KEY,
}

url = 'https://api.annolab.ai/v1/agents/ownership-chain/1842/stop'

response = requests.post(url, headers=headers)

print(response.json())
```

{% endtab %}
{% endtabs %}