Run: Sources

The Sources API manages the package sources that Hoody Run uses to resolve and search packages. Use these endpoints to list configured sources, add new entries, partially update or delete existing ones, trigger sync jobs for one source or all sources, and read runtime health diagnostics for troubleshooting.

All endpoints run against the Run service inside your container. Substitute {projectId}, {containerId}, and {server} in the base URL with your actual identifiers, and authenticate by sending a Bearer token in the Authorization header.

Read sources

`GET /api/v1/run/sources`

Returns every configured package source, including its provider, type, priority, enabled state, and provider-specific configuration.

This endpoint takes no parameters.

curl https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com/api/v1/run/sources \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.run.sources.listSources();

[
  {
    "source_id": "nixpkgs",
    "enabled": true,
    "priority": 100,
    "provider": "nix",
    "source_type": "nix-pkgs",
    "config": {
      "flake": "nixpkgs"
    }
  },
  {
    "source_id": "pkgx",
    "enabled": true,
    "priority": 90,
    "provider": "pkgx",
    "source_type": "pkgx",
    "config": {
      "mirror": "https://pkgx.sh"
    }
  }
]

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

Returns runtime health and observability data for a single source, including recent search and sync timing, the most recent error, and provider-specific details.

Parameters

Name	In	Type	Required	Description
source_id	path	string	Yes	Source identifier

curl https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com/api/v1/run/sources/nixpkgs/diagnostics \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

{
  "source_id": "nixpkgs",
  "status": "ok",
  "last_success_at": "2025-01-15T10:25:14Z",
  "last_search_latency_ms": 142,
  "last_sync_job_id": "550e8400-e29b-41d4-a716-446655440000",
  "cache_hint": "fresh",
  "effective_enabled_reason": "configured-enabled",
  "provider_details": {
    "flake_rev": "abc1234",
    "cached_packages": 8421
  }
}

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

Modify sources

`POST /api/v1/run/sources`

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

This endpoint takes no parameters.

Request Body

Send a SourceConfig object as JSON. The required fields are source_id, enabled, priority, provider, and source_type.

{
  "source_id": "nixpkgs-unstable",
  "enabled": true,
  "priority": 80,
  "provider": "nix",
  "source_type": "nix-flake",
  "pin": {
    "url": "https://github.com/NixOS/nixpkgs/archive/nixpkgs-unstable.tar.gz"
  },
  "config": {
    "flake": "nixpkgs-unstable"
  }
}

curl -X POST https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com/api/v1/run/sources \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "nixpkgs-unstable",
    "enabled": true,
    "priority": 80,
    "provider": "nix",
    "source_type": "nix-flake",
    "config": {
      "flake": "nixpkgs-unstable"
    }
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

[
  {
    "source_id": "nixpkgs",
    "enabled": true,
    "priority": 100,
    "provider": "nix",
    "source_type": "nix-pkgs",
    "config": {
      "flake": "nixpkgs"
    }
  },
  {
    "source_id": "nixpkgs-unstable",
    "enabled": true,
    "priority": 80,
    "provider": "nix",
    "source_type": "nix-flake",
    "config": {
      "flake": "nixpkgs-unstable"
    }
  }
]

{
  "error": "The source configuration did not include a non-empty 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

{
  "error": "A source with the same source_id 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

{
  "error": "The updated source configuration could not be persisted",
  "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

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

Partially updates a source configuration. Supports merging enabled, priority, pin, and config fields without touching other settings.

Parameters

Name	In	Type	Required	Description
source_id	path	string	Yes	Source identifier

Request Body

Send any subset of SourceConfig fields you want to update. The body is a free-form object; only fields you supply are merged into the existing configuration.

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

curl -X PATCH https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com/api/v1/run/sources/nixpkgs \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false,
    "priority": 120
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

{
  "source_id": "nixpkgs",
  "enabled": false,
  "priority": 120,
  "provider": "nix",
  "source_type": "nix-pkgs",
  "config": {
    "flake": "nixpkgs"
  }
}

{
  "error": "No source exists with the requested source_id",
  "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

{
  "error": "The updated source configuration could not be persisted",
  "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 /api/v1/run/sources/{source_id}`

Removes a package source by its ID. Returns 204 on success.

Parameters

Name	In	Type	Required	Description
source_id	path	string	Yes	Source identifier

curl -X DELETE https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com/api/v1/run/sources/nixpkgs \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

{
  "error": "No source exists with the requested source_id",
  "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

{
  "error": "The updated source configuration could not be persisted",
  "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 sources

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

Triggers a sync operation for the specified source. Returns immediately with a job handle; poll the Jobs API to track progress and completion.

Parameters

Name	In	Type	Required	Description
source_id	path	string	Yes	Source identifier

curl -X POST https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com/api/v1/run/sources/nixpkgs/sync \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

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

{
  "error": "The source sync job could not be started",
  "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

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

Triggers a sync operation for every enabled source. Returns immediately with a job handle. Poll for completion with GET /api/v1/run/jobs/{job_id}?wait=done&timeout_ms=30000.

This endpoint takes no parameters.

curl -X POST https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com/api/v1/run/sources/sync \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.run.sources.syncAllSources();

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

{
  "error": "The all-sources sync job could not be started",
  "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