# Artifacts API

Artifacts are verifiable proof objects generated during AI execution. They provide transparent decision-making records including task plans, implementation plans, walkthroughs, verification proofs, decision records, code changes, and research summaries. Artifacts support status tracking, comments, version chains via superseding, and can be linked to conversations, messages, or workflow runs. Rate-limited to 120 requests per minute.

---

## Artifact Metadata

Public endpoint for discovering available artifact types and statuses. No authentication required.

### GET /api/v2/artifacts/meta/types

Returns the list of supported artifact types and valid status values.

**Example Request**

```bash
curl -X GET https://api.lvng.ai/api/v2/artifacts/meta/types
```

**Response -- 200**

```json
{
  "success": true,
  "data": {
    "types": {
      "TASK_PLAN": "task_plan",
      "IMPLEMENTATION_PLAN": "implementation_plan",
      "WALKTHROUGH": "walkthrough",
      "VERIFICATION_PROOF": "verification_proof",
      "DECISION_RECORD": "decision_record",
      "PLAN_MODE": "plan_mode",
      "CODE_CHANGE": "code_change",
      "RESEARCH_SUMMARY": "research_summary"
    },
    "statuses": {
      "DRAFT": "draft",
      "PENDING_REVIEW": "pending_review",
      "APPROVED": "approved",
      "REJECTED": "rejected",
      "SUPERSEDED": "superseded"
    }
  }
}
```

---

## Artifact CRUD

Create, retrieve, update, and delete artifacts. All authenticated endpoints require a workspace context via the `x-workspace-id` header or `workspace_id` query parameter.

### GET /api/v2/artifacts

List artifacts with optional filters. Requires workspace context.

**Query Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `type` | string | No | Filter by artifact type (task_plan, implementation_plan, walkthrough, verification_proof, decision_record, plan_mode, code_change, research_summary). |
| `status` | string | No | Filter by status (draft, pending_review, approved, rejected, superseded). |
| `workflow_id` | uuid | No | Filter by associated workflow ID. |
| `workflow_run_id` | uuid | No | Filter by workflow run ID. |
| `conversation_id` | uuid | No | Filter by conversation ID. |
| `message_id` | uuid | No | Filter by message ID. |
| `limit` | integer | No | Maximum number of artifacts to return. Default: `50` |
| `offset` | integer | No | Pagination offset. Default: `0` |

**Example Request**

```bash
curl -X GET "https://api.lvng.ai/api/v2/artifacts?type=code_change&status=approved&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-workspace-id: b2c3d4e5-f6a7-8901-bcde-f23456789012"
```

**Response -- 200**

```json
{
  "success": true,
  "data": [
    {
      "id": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e",
      "workspace_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "type": "code_change",
      "title": "API Rate Limiter Middleware",
      "content": { "diff": "...", "language": "javascript" },
      "status": "approved",
      "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "confidence_score": 0.92,
      "created_at": "2026-03-15T16:20:00.000Z"
    }
  ],
  "meta": { "count": 2, "limit": 10, "offset": 0 }
}
```

---

### GET /api/v2/artifacts/:id

Get a single artifact by ID including its full content.

**Path Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | uuid | Yes | The artifact ID. |

**Example Request**

```bash
curl -X GET https://api.lvng.ai/api/v2/artifacts/7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-workspace-id: b2c3d4e5-f6a7-8901-bcde-f23456789012"
```

**Response -- 200**

```json
{
  "success": true,
  "data": {
    "id": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e",
    "workspace_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "type": "code_change",
    "title": "API Rate Limiter Middleware",
    "content": {
      "diff": "+import rateLimit from 'express-rate-limit';\n+const limiter = rateLimit({ windowMs: 15 * 60 * 1000, max: 100 });",
      "language": "javascript",
      "file_path": "src/middleware/rate-limit.js"
    },
    "status": "approved",
    "parent_artifact_id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d",
    "confidence_score": 0.92,
    "review_policy": "agent_decides",
    "created_at": "2026-03-15T16:20:00.000Z",
    "updated_at": "2026-03-18T09:10:00.000Z"
  }
}
```

---

### POST /api/v2/artifacts

Create a new artifact.

**Body Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `type` | string | Yes | Artifact type: task_plan, implementation_plan, walkthrough, verification_proof, decision_record, plan_mode, code_change, or research_summary. |
| `subtype` | string | No | Optional subtype for further classification. |
| `title` | string | Yes | Descriptive title for the artifact. |
| `content` | object | No | Artifact content (structure varies by type). Defaults to empty object. |
| `workflow_id` | uuid | No | Associated workflow ID. |
| `workflow_run_id` | uuid | No | Associated workflow run ID. |
| `parent_artifact_id` | uuid | No | Parent artifact ID for version chains. |
| `related_artifacts` | uuid[] | No | Array of related artifact IDs. |
| `conversation_id` | uuid | No | Conversation that produced this artifact. |
| `message_id` | uuid | No | Specific message that produced this artifact. |
| `confidence` | object | No | Confidence scoring object with score field. |
| `review_policy` | string | No | Review policy: always_proceed, agent_decides, or request_review. |

**Example Request**

```bash
curl -X POST https://api.lvng.ai/api/v2/artifacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-workspace-id: b2c3d4e5-f6a7-8901-bcde-f23456789012" \
  -d '{
    "type": "task_plan",
    "title": "Implement OAuth2 Authentication Flow",
    "content": {
      "objective": "Add OAuth2 support for third-party integrations",
      "steps": [
        { "id": 1, "description": "Install passport-oauth2 dependency", "estimated_time": "5m" },
        { "id": 2, "description": "Create OAuth strategy configuration", "estimated_time": "30m" },
        { "id": 3, "description": "Add callback route handler", "estimated_time": "20m" },
        { "id": 4, "description": "Write integration tests", "estimated_time": "45m" }
      ],
      "total_estimated_time": "1h 40m"
    },
    "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "review_policy": "request_review"
  }'
```

**Response -- 201**

```json
{
  "success": true,
  "data": {
    "id": "9e0f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
    "workspace_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "type": "task_plan",
    "title": "Implement OAuth2 Authentication Flow",
    "status": "draft",
    "review_policy": "request_review",
    "created_at": "2026-03-19T10:30:00.000Z"
  }
}
```

---

### PATCH /api/v2/artifacts/:id

Update an artifact's title, content, confidence, or review policy.

**Path Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | uuid | Yes | The artifact ID. |

**Body Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `title` | string | No | Updated title. |
| `content` | object | No | Updated content object. |
| `confidence` | object | No | Updated confidence scoring. |
| `review_policy` | string | No | Updated review policy. |

**Example Request**

```bash
curl -X PATCH https://api.lvng.ai/api/v2/artifacts/9e0f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-workspace-id: b2c3d4e5-f6a7-8901-bcde-f23456789012" \
  -d '{
    "title": "Implement OAuth2 Authentication Flow (Updated)",
    "confidence": { "score": 0.95 }
  }'
```

**Response -- 200**

```json
{
  "success": true,
  "data": {
    "id": "9e0f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
    "type": "task_plan",
    "title": "Implement OAuth2 Authentication Flow (Updated)",
    "status": "draft",
    "confidence_score": 0.95,
    "updated_at": "2026-03-19T10:45:00.000Z"
  }
}
```

---

### DELETE /api/v2/artifacts/:id

Permanently delete an artifact.

**Path Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | uuid | Yes | The artifact ID. |

**Example Request**

```bash
curl -X DELETE https://api.lvng.ai/api/v2/artifacts/9e0f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-workspace-id: b2c3d4e5-f6a7-8901-bcde-f23456789012"
```

**Response -- 200**

```json
{
  "success": true,
  "message": "Artifact deleted"
}
```

---

## Status & Comments

Transition artifacts through their lifecycle and add review comments.

### POST /api/v2/artifacts/:id/status

Transition an artifact to a new status.

**Path Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | uuid | Yes | The artifact ID. |

**Body Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `status` | string | Yes | New status: draft, pending_review, approved, rejected, or superseded. |

**Example Request**

```bash
curl -X POST https://api.lvng.ai/api/v2/artifacts/9e0f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b/status \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-workspace-id: b2c3d4e5-f6a7-8901-bcde-f23456789012" \
  -d '{ "status": "approved" }'
```

**Response -- 200**

```json
{
  "success": true,
  "data": {
    "id": "9e0f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
    "status": "approved",
    "reviewed_by": "8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "updated_at": "2026-03-19T11:00:00.000Z"
  }
}
```

---

### POST /api/v2/artifacts/:id/comments

Add a comment to an artifact.

**Path Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | uuid | Yes | The artifact ID. |

**Body Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `content` | string | Yes | The comment text. |
| `position` | object | No | Optional position data for inline comments (e.g., line numbers, offsets). |

**Example Request**

```bash
curl -X POST https://api.lvng.ai/api/v2/artifacts/9e0f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b/comments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-workspace-id: b2c3d4e5-f6a7-8901-bcde-f23456789012" \
  -d '{
    "content": "Looks good. Consider adding rate limiting per IP in addition to per user.",
    "position": { "step_id": 2 }
  }'
```

**Response -- 201**

```json
{
  "success": true,
  "data": {
    "id": "9e0f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
    "comments": [
      {
        "id": "cmt_4b5c6d7e-8f9a-0b1c-2d3e-4f5a6b7c8d9e",
        "user_id": "8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
        "content": "Looks good. Consider adding rate limiting per IP in addition to per user.",
        "position": { "step_id": 2 },
        "created_at": "2026-03-19T11:15:00.000Z"
      }
    ]
  }
}
```

---

## Version Chain

Artifacts can be superseded to create version chains. When an artifact is superseded, its status is set to "superseded" and a new artifact is created with a `parent_artifact_id` linking back to the original.

### POST /api/v2/artifacts/:id/supersede

Create a new version of an artifact. The original is marked as superseded.

**Path Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | uuid | Yes | The artifact ID to supersede. |

**Body Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `title` | string | No | Title for the new version. Defaults to original title. |
| `content` | object | No | Content for the new version. Defaults to original content. |
| `confidence` | object | No | Confidence scoring for the new version. |

**Example Request**

```bash
curl -X POST https://api.lvng.ai/api/v2/artifacts/7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e/supersede \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-workspace-id: b2c3d4e5-f6a7-8901-bcde-f23456789012" \
  -d '{
    "title": "API Rate Limiter Middleware v4",
    "content": {
      "diff": "+const limiter = rateLimit({ windowMs: 15 * 60 * 1000, max: 200, keyGenerator: (req) => req.ip });",
      "language": "javascript"
    }
  }'
```

**Response -- 201**

```json
{
  "success": true,
  "data": {
    "id": "f1a2b3c4-d5e6-f7a8-b9c0-d1e2f3a4b5c6",
    "type": "code_change",
    "title": "API Rate Limiter Middleware v4",
    "status": "draft",
    "parent_artifact_id": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e",
    "created_at": "2026-03-19T12:00:00.000Z"
  }
}
```

---

### GET /api/v2/artifacts/:id/chain

Get the full version chain for an artifact. Traverses parent_artifact_id links.

**Path Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | uuid | Yes | The ID of any artifact in the chain. |

**Example Request**

```bash
curl -X GET https://api.lvng.ai/api/v2/artifacts/7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e/chain \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-workspace-id: b2c3d4e5-f6a7-8901-bcde-f23456789012"
```

**Response -- 200**

```json
{
  "success": true,
  "data": [
    { "id": "3a4b5c6d-7e8f-9a0b-1c2d-3e4f5a6b7c8d", "title": "API Rate Limiter Middleware", "status": "superseded", "parent_artifact_id": null, "created_at": "2026-03-10T08:00:00.000Z" },
    { "id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d", "title": "API Rate Limiter Middleware", "status": "superseded", "parent_artifact_id": "3a4b5c6d-7e8f-9a0b-1c2d-3e4f5a6b7c8d", "created_at": "2026-03-12T14:30:00.000Z" },
    { "id": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e", "title": "API Rate Limiter Middleware", "status": "superseded", "parent_artifact_id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d", "created_at": "2026-03-15T16:20:00.000Z" },
    { "id": "f1a2b3c4-d5e6-f7a8-b9c0-d1e2f3a4b5c6", "title": "API Rate Limiter Middleware v4", "status": "draft", "parent_artifact_id": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e", "created_at": "2026-03-19T12:00:00.000Z" }
  ]
}
```

---

## Context Queries

Fetch artifacts by their context -- either the conversation they were created in or the workflow run that produced them.

### GET /api/v2/artifacts/conversation/:conversationId

Get all artifacts associated with a conversation.

**Path Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `conversationId` | uuid | Yes | The conversation ID. |

**Example Request**

```bash
curl -X GET https://api.lvng.ai/api/v2/artifacts/conversation/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-workspace-id: b2c3d4e5-f6a7-8901-bcde-f23456789012"
```

**Response -- 200**

```json
{
  "success": true,
  "data": [
    {
      "id": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e",
      "type": "code_change",
      "title": "API Rate Limiter Middleware",
      "status": "approved",
      "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2026-03-15T16:20:00.000Z"
    }
  ]
}
```

---

### GET /api/v2/artifacts/workflow/:runId

Get all artifacts produced by a specific workflow execution run.

**Path Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `runId` | uuid | Yes | The workflow run ID. |

**Example Request**

```bash
curl -X GET https://api.lvng.ai/api/v2/artifacts/workflow/e5f6a7b8-c9d0-1234-ef56-789012345678 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-workspace-id: b2c3d4e5-f6a7-8901-bcde-f23456789012"
```

**Response -- 200**

```json
{
  "success": true,
  "data": [
    {
      "id": "ab12cd34-ef56-7890-abcd-ef1234567890",
      "type": "task_plan",
      "title": "Sales Report Generation Plan",
      "status": "approved",
      "workflow_run_id": "e5f6a7b8-c9d0-1234-ef56-789012345678",
      "created_at": "2026-03-19T18:00:01.000Z"
    },
    {
      "id": "bc23de45-f678-9012-bcde-f23456789012",
      "type": "walkthrough",
      "title": "Sales Report Generation - Execution Summary",
      "status": "approved",
      "workflow_run_id": "e5f6a7b8-c9d0-1234-ef56-789012345678",
      "created_at": "2026-03-19T18:00:47.000Z"
    }
  ]
}
```