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.

cURL

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

SDK

await client.run.sources.listSources()

Response 200

[
  {
    "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

cURL

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

SDK

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

Response 200

{
  "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": {}
}

Response 404

{
  "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)

{
  "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"
  }
}

cURL

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"}
  }'

SDK

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

Response 200

[
  {
    "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"
    }
  }
]

Response 400

{
  "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

Response 409

{
  "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

Response 503

{
  "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.

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

cURL

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
  }'

SDK

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

Response 200

{
  "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"
  }
}

Response 404

{
  "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

Response 503

{
  "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

cURL

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

SDK

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

Response 204

No response body.

Response 404

{
  "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

Response 503

{
  "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

cURL

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

SDK

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

Response 202

{
  "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"
}

Response 503

{
  "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.

cURL

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

SDK

await client.run.sources.syncAllSources()

Response 202

{
  "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"
}

Response 503

{
  "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