# Run: Sources

**Page:** api/run/sources

[Download Raw Markdown](./api/run/sources.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



# Run: Sources

Manage application sources — list, create, update, delete, sync, and diagnose.

The Run service resolves package candidates from one or more configured sources. These endpoints let you inspect the current configuration, add or modify sources, remove sources that are no longer needed, trigger syncs to refresh source metadata, and pull runtime diagnostics for troubleshooting search and sync failures.

All endpoints are scoped to a specific container instance. Requests are sent to:
`https://{projectId}-{containerId}-run-1.{server}.containers.hoody.icu`

## List sources

### `GET /api/v1/run/sources`

List all configured package sources with their type, provider, priority, enabled state, and provider-specific configuration.

This endpoint takes no parameters.



```bash
curl https://proj1-cnt1-run-1.us-east.containers.hoody.icu/api/v1/run/sources
```


```javascript
await client.run.sources.listSources()
```


```json
[
  {
    "source_id": "nixpkgs",
    "enabled": true,
    "priority": 80,
    "provider": "nix",
    "source_type": "nix-pkgs"
  },
  {
    "source_id": "nixpkgs-stable",
    "enabled": true,
    "priority": 100,
    "provider": "nix",
    "source_type": "nix-flake",
    "pin": {
      "url": "https://github.com/NixOS/nixpkgs/archive/refs/heads/nixos-unstable.tar.gz"
    },
    "config": {
      "flake": "nixpkgs"
    }
  }
]
```



## Get source diagnostics

### `GET /api/v1/run/sources/{source_id}/diagnostics`

Return runtime-only health and observability data for a configured source, including recent search or sync failures.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `source_id` | path | string | Yes | Source identifier |



```bash
curl https://proj1-cnt1-run-1.us-east.containers.hoody.icu/api/v1/run/sources/nixpkgs/diagnostics
```


```javascript
await client.run.sources.getSourceDiagnostics("nixpkgs")
```


```json
{
  "source_id": "nixpkgs",
  "status": "ok",
  "last_success_at": "2025-01-15T10:30:00Z",
  "last_error_at": null,
  "last_error": null,
  "last_search_latency_ms": 42,
  "last_sync_job_id": "550e8400-e29b-41d4-a716-446655440000",
  "cache_hint": "fresh",
  "effective_enabled_reason": null,
  "provider_details": {}
}
```


```json
{
  "error": "Source not found",
  "code": 404
}
```



## Create source

### `POST /api/v1/run/sources`

Add a new package source configuration. The source is appended to the existing list and is immediately available for searches if enabled.

### Request Body

The request body is a complete `SourceConfig` object.

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `source_id` | string | Yes | Unique source identifier |
| `enabled` | boolean | Yes | Whether this source is active for searches |
| `priority` | integer | Yes | Source priority (higher values are searched first and ranked higher) |
| `provider` | string | Yes | Package source provider kind (one of `nix`, `pkgx`, `appimage`, `oci`, `registry`, `system`, `any`) |
| `source_type` | string | Yes | Specific source implementation type (e.g. `nix-flake`, `nix-pkgs`, `pkgx`, `app-image-pinned`) |
| `pin` | object | No | Pin configuration including URL and optional integrity verification fields |
| `config` | object | No | Provider-specific configuration (varies by source_type) |

```json
{
  "source_id": "nixpkgs-stable",
  "enabled": true,
  "priority": 100,
  "provider": "nix",
  "source_type": "nix-flake",
  "pin": {
    "url": "https://github.com/NixOS/nixpkgs/archive/refs/heads/nixos-unstable.tar.gz"
  },
  "config": {
    "flake": "nixpkgs"
  }
}
```



```bash
curl -X POST https://proj1-cnt1-run-1.us-east.containers.hoody.icu/api/v1/run/sources \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "nixpkgs-stable",
    "enabled": true,
    "priority": 100,
    "provider": "nix",
    "source_type": "nix-flake",
    "config": {"flake": "nixpkgs"}
  }'
```


```javascript
await client.run.sources.createSource({
  source_id: "nixpkgs-stable",
  enabled: true,
  priority: 100,
  provider: "nix",
  source_type: "nix-flake",
  config: { flake: "nixpkgs" }
})
```


```json
[
  {
    "source_id": "nixpkgs",
    "enabled": true,
    "priority": 80,
    "provider": "nix",
    "source_type": "nix-pkgs"
  },
  {
    "source_id": "nixpkgs-stable",
    "enabled": true,
    "priority": 100,
    "provider": "nix",
    "source_type": "nix-flake",
    "pin": {
      "url": "https://github.com/NixOS/nixpkgs/archive/refs/heads/nixos-unstable.tar.gz"
    },
    "config": {
      "flake": "nixpkgs"
    }
  }
]
```


```json
{
  "error": "Missing source_id",
  "code": 400
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `MISSING_SOURCE_ID` | Missing source identifier | The source configuration did not include a non-empty source_id | Set source_id before creating the source |


```json
{
  "error": "Source already exists",
  "code": 409
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `SOURCE_ALREADY_EXISTS` | Source already exists | A source with the same source_id already exists | Choose a unique source_id or update the existing source instead |


```json
{
  "error": "Configuration save failed",
  "code": 503
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `CONFIG_SAVE_FAILED` | Configuration save failed | The updated source configuration could not be persisted | Check storage health and retry |



## Update source

### `PATCH /api/v1/run/sources/{source_id}`

Partially update a source configuration. Supports merging `enabled`, `priority`, `pin`, and `config` fields. Only the fields included in the body are modified.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `source_id` | path | string | Yes | Source identifier |

### Request Body

Provide any subset of `SourceConfig` fields to update. Only the fields included in the body are modified; omitted fields retain their existing values.

```json
{
  "enabled": false,
  "priority": 50
}
```



```bash
curl -X PATCH https://proj1-cnt1-run-1.us-east.containers.hoody.icu/api/v1/run/sources/nixpkgs \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false,
    "priority": 50
  }'
```


```javascript
await client.run.sources.updateSource("nixpkgs", {
  enabled: false,
  priority: 50
})
```


```json
{
  "source_id": "nixpkgs",
  "enabled": false,
  "priority": 50,
  "provider": "nix",
  "source_type": "nix-flake",
  "pin": {
    "url": "https://github.com/NixOS/nixpkgs/archive/refs/heads/nix-unstable.tar.gz"
  },
  "config": {
    "flake": "nixpkgs"
  }
}
```


```json
{
  "error": "Source not found",
  "code": 404
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `SOURCE_NOT_FOUND` | Source not found | No source exists with the requested source_id | Call listSources and choose a valid source_id |


```json
{
  "error": "Configuration save failed",
  "code": 503
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `CONFIG_SAVE_FAILED` | Configuration save failed | The updated source configuration could not be persisted | Check storage health and retry |



## Delete source

### `DELETE /api/v1/run/sources/{source_id}`

Remove a package source by its ID. Returns `204` on success with no body.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `source_id` | path | string | Yes | Source identifier |



```bash
curl -X DELETE https://proj1-cnt1-run-1.us-east.containers.hoody.icu/api/v1/run/sources/nixpkgs
```


```javascript
await client.run.sources.deleteSource("nixpkgs")
```


```
No response body.
```


```json
{
  "error": "Source not found",
  "code": 404
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `SOURCE_NOT_FOUND` | Source not found | No source exists with the requested source_id | Call listSources and choose a valid source_id |


```json
{
  "error": "Configuration save failed",
  "code": 503
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `CONFIG_SAVE_FAILED` | Configuration save failed | The updated source configuration could not be persisted | Check storage health and retry |



## Sync single source

### `POST /api/v1/run/sources/{source_id}/sync`

Trigger a sync operation for a specific source. Returns immediately with a job handle for tracking progress via the jobs endpoint.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `source_id` | path | string | Yes | Source identifier |



```bash
curl -X POST https://proj1-cnt1-run-1.us-east.containers.hoody.icu/api/v1/run/sources/nixpkgs/sync
```


```javascript
await client.run.sources.syncSource("nixpkgs")
```


```json
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "kind": "source-sync",
  "status": "queued",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}
```


```json
{
  "error": "Sync start failed",
  "code": 503
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `SYNC_START_FAILED` | Sync start failed | The source sync job could not be started | Retry or inspect source/provider health |



## Sync all sources

### `POST /api/v1/run/sources/sync`

Trigger a sync operation for all enabled sources. Returns immediately with a job handle. Use `GET /api/v1/run/jobs/{job_id}?wait=done&timeout_ms=30000` to poll for completion.

This endpoint takes no parameters.



```bash
curl -X POST https://proj1-cnt1-run-1.us-east.containers.hoody.icu/api/v1/run/sources/sync
```


```javascript
await client.run.sources.syncAllSources()
```


```json
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "kind": "source-sync",
  "status": "queued",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}
```


```json
{
  "error": "Sync start failed",
  "code": 503
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `SYNC_START_FAILED` | Sync start failed | The all-sources sync job could not be started | Retry or inspect source/provider health |