# Code Index

Source: https://opvs.ai/docs/api/code-index

## `POST` /api/v1/code/index

**Ingest Index**

Store one structural scan of a tenant repo.

**Request body**

```bash
curl -X POST 'https://app.opvs.ai/api/v1/code/index' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "project_id": "string",
  "repo_url": "string",
  "commit_hash": "string",
  "branch": "string",
  "symbols": [
    {
      "name": "string",
      "kind": "string",
      "file_path": "string",
      "line_start": 0,
      "line_end": 0,
      "signature": "string",
      "doc_first_line": "string",
      "derivation": "parsed",
      "language": "string",
      "decorators": [
        "string"
      ]
    }
  ],
  "languages": {},
  "entry_points": [
    {}
  ],
  "test_command": "string",
  "truncated": false,
  "truncated_reason": "string",
  "wall_clock_cut": false,
  "semantic_edges_truncated_reason": "string",
  "tool_version": "string",
  "knowledge_files": [
    {
      "path": "string",
      "sha256": "string",
      "content": "string"
    }
  ],
  "knowledge_truncated": {
    "reason": "string"
  },
  "resolved_anchors": [
    {
      "anchor": "string",
      "node_id": "00000000-0000-0000-0000-000000000000",
      "node_path": "string",
      "state": "string",
      "anchor_missing": true,
      "ancestor_node_ids": [
        "00000000-0000-0000-0000-000000000000"
      ]
    }
  ],
  "commit_time": "2026-01-01T00:00:00Z",
  "directories": [
    {
      "path": "string",
      "files": 0,
      "lines": 0,
      "files_scanned": 0
    }
  ],
  "scan_contract": 0,
  "files": [
    {
      "path": "string",
      "sha": "string",
      "language": "string",
      "scanned": true
    }
  ]
}'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/code/index",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"project_id": "string", "repo_url": "string", "commit_hash": "string", "branch": "string", "symbols": [{"name": "string", "kind": "string", "file_path": "string", "line_start": 0, "line_end": 0, "signature": "string", "doc_first_line": "string", "derivation": "parsed", "language": "string", "decorators": ["string"]}], "languages": {}, "entry_points": [{}], "test_command": "string", "truncated": false, "truncated_reason": "string", "wall_clock_cut": false, "semantic_edges_truncated_reason": "string", "tool_version": "string", "knowledge_files": [{"path": "string", "sha256": "string", "content": "string"}], "knowledge_truncated": {"reason": "string"}, "resolved_anchors": [{"anchor": "string", "node_id": "00000000-0000-0000-0000-000000000000", "node_path": "string", "state": "string", "anchor_missing": true, "ancestor_node_ids": ["00000000-0000-0000-0000-000000000000"]}], "commit_time": "2026-01-01T00:00:00Z", "directories": [{"path": "string", "files": 0, "lines": 0, "files_scanned": 0}], "scan_contract": 0, "files": [{"path": "string", "sha": "string", "language": "string", "scanned": true}]},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/code/index", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"project_id": "string", "repo_url": "string", "commit_hash": "string", "branch": "string", "symbols": [{"name": "string", "kind": "string", "file_path": "string", "line_start": 0, "line_end": 0, "signature": "string", "doc_first_line": "string", "derivation": "parsed", "language": "string", "decorators": ["string"]}], "languages": {}, "entry_points": [{}], "test_command": "string", "truncated": false, "truncated_reason": "string", "wall_clock_cut": false, "semantic_edges_truncated_reason": "string", "tool_version": "string", "knowledge_files": [{"path": "string", "sha256": "string", "content": "string"}], "knowledge_truncated": {"reason": "string"}, "resolved_anchors": [{"anchor": "string", "node_id": "00000000-0000-0000-0000-000000000000", "node_path": "string", "state": "string", "anchor_missing": true, "ancestor_node_ids": ["00000000-0000-0000-0000-000000000000"]}], "commit_time": "2026-01-01T00:00:00Z", "directories": [{"path": "string", "files": 0, "lines": 0, "files_scanned": 0}], "scan_contract": 0, "files": [{"path": "string", "sha": "string", "language": "string", "scanned": true}]})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"project_id": "string", "repo_url": "string", "commit_hash": "string", "branch": "string", "symbols": [{"name": "string", "kind": "string", "file_path": "string", "line_start": 0, "line_end": 0, "signature": "string", "doc_first_line": "string", "derivation": "parsed", "language": "string", "decorators": ["string"]}], "languages": {}, "entry_points": [{}], "test_command": "string", "truncated": false, "truncated_reason": "string", "wall_clock_cut": false, "semantic_edges_truncated_reason": "string", "tool_version": "string", "knowledge_files": [{"path": "string", "sha256": "string", "content": "string"}], "knowledge_truncated": {"reason": "string"}, "resolved_anchors": [{"anchor": "string", "node_id": "00000000-0000-0000-0000-000000000000", "node_path": "string", "state": "string", "anchor_missing": true, "ancestor_node_ids": ["00000000-0000-0000-0000-000000000000"]}], "commit_time": "2026-01-01T00:00:00Z", "directories": [{"path": "string", "files": 0, "lines": 0, "files_scanned": 0}], "scan_contract": 0, "files": [{"path": "string", "sha": "string", "language": "string", "scanned": true}]}`)
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/code/index", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `201` — Successful Response
- `422` — Validation Error

## `POST` /api/v1/code/index/{index_id}/failed

**Report Failed**

Record that a scan the caller started could not be completed.

**Parameters**

- `index_id` (path, string, required)

**Request body**

```bash
curl -X POST 'https://app.opvs.ai/api/v1/code/index/{index_id}/failed' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "error_message": "string"
}'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/code/index/{index_id}/failed",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"error_message": "string"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/code/index/{index_id}/failed", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"error_message": "string"})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"error_message": "string"}`)
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/code/index/{index_id}/failed", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `POST` /api/v1/code/jobs/claim

**Claim Index Job**

Lease this brand's oldest claimable index job to the calling desk.

**Request body**

```bash
curl -X POST 'https://app.opvs.ai/api/v1/code/jobs/claim' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/code/jobs/claim",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/code/jobs/claim", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{}`)
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/code/jobs/claim", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `204` — Nothing to index for this brand right now
- `422` — Validation Error

## `POST` /api/v1/code/jobs/{job_id}/result

**Post Index Job Result**

Store the scan of a job this desk holds, and end the job.

**Parameters**

- `job_id` (path, string, required)

**Request body**

```bash
curl -X POST 'https://app.opvs.ai/api/v1/code/jobs/{job_id}/result' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/code/jobs/{job_id}/result",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/code/jobs/{job_id}/result", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{}`)
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/code/jobs/{job_id}/result", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `POST` /api/v1/code/jobs/{job_id}/failed

**Report Index Job Failed**

The desk could not finish a job it holds.

**Parameters**

- `job_id` (path, string, required)

**Request body**

```bash
curl -X POST 'https://app.opvs.ai/api/v1/code/jobs/{job_id}/failed' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "reason_class": "download_failed",
  "detail": "string"
}'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/code/jobs/{job_id}/failed",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"reason_class": "download_failed", "detail": "string"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/code/jobs/{job_id}/failed", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"reason_class": "download_failed", "detail": "string"})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"reason_class": "download_failed", "detail": "string"}`)
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/code/jobs/{job_id}/failed", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/code/{project_id}/context

**Code Context**

"Does this already exist?" — the pre-write check.

**Parameters**

- `project_id` (path, string, required)
- `query` (query, string, required) — Symbol name or phrase to look for
- `kind` (query, any, optional) — Restrict to one symbol kind
- `branch` (query, any, optional) — Which indexed branch to answer from
- `limit` (query, any, optional) — Max matches to return
- `format` (query, any, optional) — Response format: yaml or md

```bash
curl -X GET 'https://app.opvs.ai/api/v1/code/{project_id}/context' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/code/{project_id}/context",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/code/{project_id}/context", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/code/{project_id}/context", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/code/{project_id}/summary

**Code Summary**

The orientation document as DATA — what 2.1 renders into a briefing.

**Parameters**

- `project_id` (path, string, required)
- `branch` (query, any, optional)
- `format` (query, any, optional) — Response format: yaml or md

```bash
curl -X GET 'https://app.opvs.ai/api/v1/code/{project_id}/summary' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/code/{project_id}/summary",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/code/{project_id}/summary", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/code/{project_id}/summary", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/code/{project_id}/tree

**Code Tree**

Where the code lives — the directory rollup behind the code-index canvas.

**Parameters**

- `project_id` (path, string, required)
- `branch` (query, any, optional)
- `depth` (query, any, optional) — Deepest directory level to return, 1-based. Narrows the response; it cannot widen it past what the ingest stored.
- `format` (query, any, optional) — Response format: yaml or md

```bash
curl -X GET 'https://app.opvs.ai/api/v1/code/{project_id}/tree' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/code/{project_id}/tree",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/code/{project_id}/tree", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/code/{project_id}/tree", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/code/{project_id}/fidelity

**Code Fidelity**

**Parameters**

- `project_id` (path, string, required)
- `branch` (query, any, optional)

```bash
curl -X GET 'https://app.opvs.ai/api/v1/code/{project_id}/fidelity' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/code/{project_id}/fidelity",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/code/{project_id}/fidelity", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/code/{project_id}/fidelity", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/code/{project_id}/files

**Code Files**

**Parameters**

- `project_id` (path, string, required)
- `directory` (query, string, optional) — Repo-relative directory; '.' is the root
- `direct` (query, boolean, optional) — Only files sitting directly in the directory, not beneath it
- `branch` (query, any, optional)
- `limit` (query, any, optional) — Max files to return
- `order` (query, string, optional) — Order by symbol count or repo-relative path
- `after` (query, any, optional) — Repo-relative path cursor; only valid with order=path
- `format` (query, any, optional) — Response format: yaml or md

```bash
curl -X GET 'https://app.opvs.ai/api/v1/code/{project_id}/files' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/code/{project_id}/files",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/code/{project_id}/files", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/code/{project_id}/files", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/code/{project_id}/symbols

**Code File Symbols**

**Parameters**

- `project_id` (path, string, required)
- `file_path` (query, string, required)
- `branch` (query, any, optional)
- `limit` (query, any, optional) — Max symbols to return
- `format` (query, any, optional) — Response format: yaml or md

```bash
curl -X GET 'https://app.opvs.ai/api/v1/code/{project_id}/symbols' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/code/{project_id}/symbols",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/code/{project_id}/symbols", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/code/{project_id}/symbols", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/code/{project_id}/jobs

**List Index Jobs**

This project's index jobs, newest first: what was asked for, and what happened.

**Parameters**

- `project_id` (path, string, required)
- `limit` (query, integer, optional)
- `offset` (query, integer, optional)
- `format` (query, any, optional) — Response format: yaml or md

```bash
curl -X GET 'https://app.opvs.ai/api/v1/code/{project_id}/jobs' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/code/{project_id}/jobs",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/code/{project_id}/jobs", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/code/{project_id}/jobs", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `POST` /api/v1/code/{project_id}/nodes/resolve

**Resolve Code Nodes**

Resolve text anchors to the current state of stable ledger nodes.

**Parameters**

- `project_id` (path, string, required)
- `format` (query, any, optional) — Response format: yaml or md

**Request body**

```bash
curl -X POST 'https://app.opvs.ai/api/v1/code/{project_id}/nodes/resolve' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "anchors": [
    "string"
  ]
}'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/code/{project_id}/nodes/resolve",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"anchors": ["string"]},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/code/{project_id}/nodes/resolve", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"anchors": ["string"]})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"anchors": ["string"]}`)
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/code/{project_id}/nodes/resolve", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `POST` /api/v1/code/{project_id}/tests-for

**Read Code Tests For**

Return test files that reach the requested files in the READY index.

**Parameters**

- `project_id` (path, string, required)
- `format` (query, any, optional) — Response format: yaml or md

**Request body**

```bash
curl -X POST 'https://app.opvs.ai/api/v1/code/{project_id}/tests-for' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "paths": [
    "string"
  ],
  "depth": 4,
  "limit": 200
}'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/code/{project_id}/tests-for",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"paths": ["string"], "depth": 4, "limit": 200},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/code/{project_id}/tests-for", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"paths": ["string"], "depth": 4, "limit": 200})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"paths": ["string"], "depth": 4, "limit": 200}`)
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/code/{project_id}/tests-for", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `POST` /api/v1/code/{project_id}/callers

**Read Code Callers**

Answer who calls up to 50 live nodes, failing open when the index is down.

**Parameters**

- `project_id` (path, string, required)

**Request body**

```bash
curl -X POST 'https://app.opvs.ai/api/v1/code/{project_id}/callers' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "node_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "callers_limit": 20,
  "tests_limit": 10
}'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/code/{project_id}/callers",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"node_ids": ["00000000-0000-0000-0000-000000000000"], "callers_limit": 20, "tests_limit": 10},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/code/{project_id}/callers", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"node_ids": ["00000000-0000-0000-0000-000000000000"], "callers_limit": 20, "tests_limit": 10})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"node_ids": ["00000000-0000-0000-0000-000000000000"], "callers_limit": 20, "tests_limit": 10}`)
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/code/{project_id}/callers", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/code/{project_id}/nodes/changes

**Code Node Changes**

The attached repo's stable-node events, oldest first unless requested.

**Parameters**

- `project_id` (path, string, required)
- `after` (query, any, optional) — Return events after this event id
- `before` (query, any, optional) — Return events before this event id
- `order` (query, string, optional) — Event id order; descending pages use the before cursor
- `limit` (query, any, optional) — Max events to return (server max 500)
- `node_id` (query, any, optional) — Stable node UUID; repeat to select up to 100 nodes
- `path_prefix` (query, any, optional) — Repo-relative path, including the path itself and descendants
- `format` (query, any, optional) — Response format: yaml or md

```bash
curl -X GET 'https://app.opvs.ai/api/v1/code/{project_id}/nodes/changes' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/code/{project_id}/nodes/changes",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/code/{project_id}/nodes/changes", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/code/{project_id}/nodes/changes", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/code/{project_id}/graph/folders

**Code Graph Folders**

Folder-level imports, hubs, and mutual pairs for the Graph overview.

**Parameters**

- `project_id` (path, string, required)
- `dir` (query, string, optional) — Repo-relative directory to roll up; defaults to the repo root
- `depth` (query, integer, optional) — Maximum folder levels below dir before deeper files are folded
- `limit` (query, any, optional) — Maximum folder rows and cross-folder link rows returned
- `branch` (query, any, optional)
- `format` (query, any, optional) — Response format: yaml or md

```bash
curl -X GET 'https://app.opvs.ai/api/v1/code/{project_id}/graph/folders' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/code/{project_id}/graph/folders",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/code/{project_id}/graph/folders", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/code/{project_id}/graph/folders", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/code/{project_id}/graph

**Code Graph**

The selected ready index's depth-one or depth-two import neighbourhood.

**Parameters**

- `project_id` (path, string, required)
- `node_id` (query, string, required) — Stable node UUID at the centre of the graph
- `direction` (query, string, optional)
- `depth` (query, integer, optional)
- `limit` (query, any, optional)
- `branch` (query, any, optional)
- `format` (query, any, optional) — Response format: yaml or md

```bash
curl -X GET 'https://app.opvs.ai/api/v1/code/{project_id}/graph' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/code/{project_id}/graph",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/code/{project_id}/graph", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/code/{project_id}/graph", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/brands/{brand_id}/code-index-runner

**Get Code Index Runner**

Read the effective choice; any active brand member may call it.

**Parameters**

- `brand_id` (path, integer, required)

```bash
curl -X GET 'https://app.opvs.ai/api/v1/brands/{brand_id}/code-index-runner' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/brands/{brand_id}/code-index-runner",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/brands/{brand_id}/code-index-runner", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/brands/{brand_id}/code-index-runner", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `PUT` /api/v1/brands/{brand_id}/code-index-runner

**Put Code Index Runner**

Create or update the choice; brand admins only.

**Parameters**

- `brand_id` (path, integer, required)

**Request body**

```bash
curl -X PUT 'https://app.opvs.ai/api/v1/brands/{brand_id}/code-index-runner' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "runner": "hosted"
}'
```

```python
import httpx

resp = httpx.put(
    "https://app.opvs.ai/api/v1/brands/{brand_id}/code-index-runner",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"runner": "hosted"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/brands/{brand_id}/code-index-runner", {
  method: "PUT",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"runner": "hosted"})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"runner": "hosted"}`)
	req, _ := http.NewRequest("PUT", "https://app.opvs.ai/api/v1/brands/{brand_id}/code-index-runner", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## Ingest Index

`POST https://app.opvs.ai/api/v1/code/index`

Store one structural scan of a tenant repo.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Report Failed

`POST https://app.opvs.ai/api/v1/code/index/{index_id}/failed`

Record that a scan the caller started could not be completed.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Claim Index Job

`POST https://app.opvs.ai/api/v1/code/jobs/claim`

Lease this brand's oldest claimable index job to the calling desk.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Post Index Job Result

`POST https://app.opvs.ai/api/v1/code/jobs/{job_id}/result`

Store the scan of a job this desk holds, and end the job.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Report Index Job Failed

`POST https://app.opvs.ai/api/v1/code/jobs/{job_id}/failed`

The desk could not finish a job it holds.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Code Context

`GET https://app.opvs.ai/api/v1/code/{project_id}/context`

"Does this already exist?" — the pre-write check.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Code Summary

`GET https://app.opvs.ai/api/v1/code/{project_id}/summary`

The orientation document as DATA — what 2.1 renders into a briefing.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Code Tree

`GET https://app.opvs.ai/api/v1/code/{project_id}/tree`

Where the code lives — the directory rollup behind the code-index canvas.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Code Fidelity

`GET https://app.opvs.ai/api/v1/code/{project_id}/fidelity`

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Code Files

`GET https://app.opvs.ai/api/v1/code/{project_id}/files`

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Code File Symbols

`GET https://app.opvs.ai/api/v1/code/{project_id}/symbols`

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## List Index Jobs

`GET https://app.opvs.ai/api/v1/code/{project_id}/jobs`

This project's index jobs, newest first: what was asked for, and what happened.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Resolve Code Nodes

`POST https://app.opvs.ai/api/v1/code/{project_id}/nodes/resolve`

Resolve text anchors to the current state of stable ledger nodes.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Read Code Tests For

`POST https://app.opvs.ai/api/v1/code/{project_id}/tests-for`

Return test files that reach the requested files in the READY index.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Read Code Callers

`POST https://app.opvs.ai/api/v1/code/{project_id}/callers`

Answer who calls up to 50 live nodes, failing open when the index is down.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Code Node Changes

`GET https://app.opvs.ai/api/v1/code/{project_id}/nodes/changes`

The attached repo's stable-node events, oldest first unless requested.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Code Graph Folders

`GET https://app.opvs.ai/api/v1/code/{project_id}/graph/folders`

Folder-level imports, hubs, and mutual pairs for the Graph overview.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Code Graph

`GET https://app.opvs.ai/api/v1/code/{project_id}/graph`

The selected ready index's depth-one or depth-two import neighbourhood.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Get Code Index Runner

`GET https://app.opvs.ai/api/v1/brands/{brand_id}/code-index-runner`

Read the effective choice; any active brand member may call it.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Put Code Index Runner

`PUT https://app.opvs.ai/api/v1/brands/{brand_id}/code-index-runner`

Create or update the choice; brand admins only.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |