Agent Builder

Agent Builder exposes two public endpoints for fetching the current user's Agent Builder configurations and their produced artifacts.

GET /v1/agent_builder/list — List all active Agent Builders owned by the current user. POST /v1/agent_builder/outputs — Fetch artifacts (structured data or HTML report) for a given agent_id.

Authentication**: Both endpoints require user authentication. The user is identified from the request context; do not pass user_id in the request. Rate limit**: 2 req/s per endpoint.

1. List Agent Builders

GET /v1/agent_builder/list

Returns all active Agent Builders owned by the current user, ordered by creation time (latest first).

Request

No request parameters. The user identity is resolved from the authentication context.

```http
GET /v1/agent_builder/list
Authorization: Bearer <token>
```

### Response

On success, `data` is an array of Agent Builders. Each item contains:

| Field | Type | Description |
|---|---|---|
| `id` | string | Agent Builder ID. Use this value as `agent_id` when calling the `outputs` endpoint. |
| `name` | string | Builder display name. |
| `description` | string \| null | Builder description. |
| `field_mapping` | object | Field-extraction schema: group → field → metadata (label, type, description, etc.). Extracted values are **not** included here; fetch them via the `outputs` endpoint. |
| `created_at` | datetime | Builder creation time. |
| `company_list` | object[] | Companies bound to this builder. Each item: `{orbit_entity_id, name}`. Empty array when no company is configured. |
| `subscriptions` | object[] | Active subscriptions attached to this builder (see table below). Empty array when no active subscription exists. |

`subscriptions[]` item fields:

| Field | Type | Description |
|---|---|---|
| `ag_sub_id` | string | Subscription ID. |
| `agent_category` | string | `AgentBuilder-Data` or `AgentBuilder-Report`. |
| `subscription_name` | string | Subscription display name. |
| `schedule_cron_expression` | string | Cron expression that triggers the subscription. |

### Errors

| Status | Message | Description |
|---|---|---|
| `404` | Agent builder info not found | The current user has no active Agent Builder. |

### Example
{
  "data": [
    {
      "id": "ab_01HXXXX...",
      "name": "Quarterly Earnings Extractor",
      "description": "Extract key financial metrics from 10-Q filings.",
      "field_mapping": {
        "financials": {
          "revenue": { "label": "Revenue", "type": "number", "description": "Total revenue (USD)" },
          "net_income": { "label": "Net Income", "type": "number", "description": "Net income (USD)" }
        }
      },
      "created_at": "2026-04-12T08:31:22Z",
      "company_list": [
        { "orbit_entity_id": "OE_0001", "name": "Apple Inc." },
        { "orbit_entity_id": "OE_0002", "name": "Microsoft Corp." }
      ],
      "subscriptions": [
        {
          "ag_sub_id": "sub_01HYYYY...",
          "agent_category": "AgentBuilder-Data",
          "subscription_name": "Daily 10-Q sweep",
          "schedule_cron_expression": "0 6 * * *"
        }
      ]
    }
  ]
}

2. Get Agent Builder Outputs

POST /v1/agent_builder/outputs

Returns artifacts produced by a specific Agent Builder, ordered by publish_date (latest first). Pagination is mandatory — every call must explicitly specify limit and offset.

Request

```http
POST /v1/agent_builder/outputs
Content-Type: application/json
Authorization: Bearer <token>
```

Request body:

| Field | Type | Required | Description |
|---|---|---|---|
| `agent_id` | string | yes | Agent Builder ID, obtained from the `list` endpoint. |
| `agent_type` | string | yes | `data` returns extracted structured data; `report` returns the HTML report URL. |
| `limit` | integer | **yes** | Maximum number of artifacts to return, range `1–50`. No implicit default. |
| `offset` | integer | **yes** | Pagination offset, `>= 0`. Pass `0` for the first page. |
| `orbit_entity_id_list` | string[] | no | Optional company filter. Effective only when `agent_type=data`; returns artifacts whose `orbit_entity_id` is in this list. Ignored when `agent_type=report`. |

> ⚠️ Every value in `orbit_entity_id_list` must originate from the `company_list` of the same builder returned by the `list` endpoint. Arbitrary external IDs are not allowed.

### Response

On success, `data` is an array of artifacts. The field set depends on `agent_type`.

**Common fields**:

| Field | Type | Description |
|---|---|---|
| `id` | string | Artifact ID. |
| `publish_date` | date | Publish date of the artifact. |
| `created_at` | datetime | Row creation time. |
| `company_list` | object[] | Companies associated with this artifact: `{orbit_entity_id, name}`. `data` artifacts typically contain a single company; `report` artifacts may contain multiple. |

**When `agent_type = data`**:

| Field | Type | Description |
|---|---|---|
| `extract_json` | object | Structured data extracted by the agent according to the builder's field schema. |

**When `agent_type = report`**:

| Field | Type | Description |
|---|---|---|
| `url` | string | Publicly accessible URL of the HTML report. |

### Errors

| Status | Message | Description |
|---|---|---|
| `404` | Agent builder meta not found | No artifact matches the given `agent_id` + `agent_type`. |
| `422` | Validation error | `limit` out of range, `offset < 0`, invalid `agent_type`, etc. |

### Example — `data`

```json
// Request
{
  "agent_id": "ab_01HXXXX...",
  "agent_type": "data",
  "limit": 20,
  "offset": 0,
  "orbit_entity_id_list": ["OE_0001"]
}
```

```json
// Response
{
  "data": [
    {
      "id": "art_01HZZZZ...",
      "publish_date": "2026-05-01",
      "created_at": "2026-05-01T03:11:45Z",
      "company_list": [
        { "orbit_entity_id": "OE_0001", "name": "Apple Inc." }
      ],
      "extract_json": {
        "financials": {
          "revenue": 124300000000,
          "net_income": 33000000000
        }
      }
    }
  ]
}
```

### Example — `report`

```json
// Request
{
  "agent_id": "ab_01HXXXX...",
  "agent_type": "report",
  "limit": 10,
  "offset": 0
}
```

```json
// Response
{
  "data": [
    {
      "id": "art_01HAAAAA...",
      "publish_date": "2026-05-10",
      "created_at": "2026-05-10T09:00:12Z",
      "company_list": [
        { "orbit_entity_id": "OE_0001", "name": "Apple Inc." },
        { "orbit_entity_id": "OE_0002", "name": "Microsoft Corp." }
      ],
      "url": "https://oassets.orbitfin.ai/reports/2026-05-10/ab_01HXXXX.html"
    }
  ]
}

Typical Workflow

1. Call GET /v1/agent_builder/list to retrieve the current user's Agent Builders. Pick the target agent_id and collect the available orbit_entity_id values from company_list.

2. Decide which artifact form to fetch:

   • agent_type=data — Retrieve structured extraction results; optionally filter by orbit_entity_id_list.

   • agent_type=report — Retrieve the HTML report URL.

3. Call POST /v1/agent_builder/outputs with mandatory limit (1–50) and offset (≥0); increment offset to paginate.

---

Rate Limit & Pagination

• Per-endpoint rate limit: 2 req/s.

• Pagination parameters on outputs are mandatory and have no default; increment offset for subsequent pages.