Run: Sources

: Sources

Manage the package sources that back the Hoody runtime. List configured sources, inspect runtime diagnostics, add or modify sources, remove them, and trigger manual syncs against one or all sources.

List and diagnostics

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://{projectId}-{containerId}-run-1.{server}.containers.hoody.com/api/v1/run/sources \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

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.list();

Response 200

[
  {
    "source_id": "nixpkgs",
    "enabled": true,
    "priority": 100,
    "provider": "nix",
    "source_type": "nix-flake",
    "pin": {
      "url": "https://github.com/NixOS/nixpkgs"
    },
    "config": {
      "flake": "nixpkgs"
    }
  },
  {
    "source_id": "system-path",
    "enabled": true,
    "priority": 50,
    "provider": "system",
    "source_type": "system-path"
  }
]

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

Return runtime health and observability data for a single source, including recent search or sync failures, the last measured latency, and a hint about cache freshness.

Parameters

Name	In	Type	Required	Description
source_id	path	string	Yes	Source identifier

cURL

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

TypeScript SDK

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.getDiagnostics('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": 142,
  "last_sync_job_id": "550e8400-e29b-41d4-a716-446655440000",
  "cache_hint": "fresh",
  "effective_enabled_reason": null,
  "provider_details": {
    "flake_rev": "abc1234"
  }
}

Response 404

{
  "error": "source not found",
  "code": "SOURCE_NOT_FOUND",
  "status": 404
}

Error Code	Title	Description	Resolution
SOURCE_NOT_FOUND	Source not found	No source exists with the requested source_id	Call client.run.sources.list() and choose a valid source_id

Create, update, and delete

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 when enabled is true.

Request Body

The request body follows the run_SourceConfig schema and configures the new source. Fields supplied are persisted as the new source record.

cURL

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

TypeScript SDK

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.create({
  source_id: 'nixpkgs',
  enabled: true,
  priority: 100,
  provider: 'nix',
  source_type: 'nix-flake',
  config: { flake: 'nixpkgs' },
});

Response 200

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

Response 400

{
  "error": "missing source_id",
  "code": "MISSING_SOURCE_ID",
  "status": 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
INVALID_SOURCE_ID	Invalid source identifier	The source_id is too long, has surrounding whitespace, or contains a path separator, ’..’, a leading dot or a control character	Use a short identifier such as my-nix-flake
SOURCE_PROVIDER_MISMATCH	Provider does not match source_type	Each source_type belongs to one provider, the pairing the default sources use (for example nix-pkgs needs nix, system-path needs system)	Set provider to the one the error message names
INVALID_SOURCE	Invalid source configuration	A manifest-remote-index source lacks pin.sha256, pin.author_pubkey_ed25519 or pin.sig_ed25519	Supply the full pin for a signed remote index
INVALID_BODY	Invalid request body	The body does not fit SourceConfig (an unknown provider or source_type, a missing or wrongly typed field)	Check the field named in the error and the SourceConfig schema

Response 409

{
  "error": "source already exists",
  "code": "SOURCE_ALREADY_EXISTS",
  "status": 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": "CONFIG_SAVE_FAILED",
  "status": 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 update a source configuration. The request body follows the run_SourceUpdate schema; only the fields supplied are merged, and fields absent from the body keep their stored value. The merged source is re-validated before it is committed, so a patch that would downgrade a signed remote index is refused.

Parameters

Name	In	Type	Required	Description
source_id	path	string	Yes	Source identifier

Request Body

The request body follows the run_SourceUpdate schema. All fields are optional. Only the fields present in the body are applied; everything else keeps its stored value.

Name	Type	Required	Description
enabled	boolean	No	Whether this source is active for searches
priority	integer	No	Source priority (higher values are searched first and ranked higher)
pin	object	No	Pin to apply. Send null to clear the pin; omit the field to keep the stored one.
config	object	No	Provider-specific configuration. Replaces the stored object as a unit.

cURL

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

TypeScript SDK

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.update('nixpkgs', {
  enabled: false,
  priority: 80,
});

Response 200

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

Response 400

{
  "error": "priority must be an integer",
  "code": "INVALID_SOURCE",
  "status": 400
}

Error Code	Title	Description	Resolution
INVALID_SOURCE	Invalid source update	enabled is not a boolean, priority is not an integer, pin does not fit SourcePin, or the patched manifest-remote-index source would lack pin.sha256, pin.author_pubkey_ed25519 or pin.sig_ed25519	Fix the field named in the error; nothing was stored
INVALID_JSON	Malformed JSON	The request body is not valid JSON	Send a JSON object

Response 404

{
  "error": "source not found",
  "code": "SOURCE_NOT_FOUND",
  "status": 404
}

Error Code	Title	Description	Resolution
SOURCE_NOT_FOUND	Source not found	No source exists with the requested source_id	Call client.run.sources.list() and choose a valid source_id

Response 503

{
  "error": "configuration save failed",
  "code": "CONFIG_SAVE_FAILED",
  "status": 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}

Remove a package source by its source_id. The endpoint returns no body on success.

Parameters

Name	In	Type	Required	Description
source_id	path	string	Yes	Source identifier

cURL

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

TypeScript SDK

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.delete('nixpkgs');

Response 204

Source deleted successfully. No content returned.

Response 404

{
  "error": "source not found",
  "code": "SOURCE_NOT_FOUND",
  "status": 404
}

Error Code	Title	Description	Resolution
SOURCE_NOT_FOUND	Source not found	No source exists with the requested source_id	Call client.run.sources.list() and choose a valid source_id

Response 503

{
  "error": "configuration save failed",
  "code": "CONFIG_SAVE_FAILED",
  "status": 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

Sync endpoints dispatch background work and return a job handle immediately. Track progress through the jobs endpoint, for example with GET /api/v1/run/jobs/{job_id}?wait=done&timeout_ms=30000.

Tip

Sync endpoints return 202 Accepted once the job is queued. They do not wait for the sync to complete, so callers must poll the job handle to observe results.

POST /api/v1/run/sources/sync

Trigger a sync operation for every enabled source. Returns immediately with a job handle for tracking progress.

This endpoint takes no parameters.

cURL

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

TypeScript SDK

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.syncAll();

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",
  "error": null
}

Response 503

{
  "error": "sync could not be started",
  "code": "SYNC_START_FAILED",
  "status": 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

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

Trigger a sync operation for a single source. Returns immediately with a job handle for tracking progress.

Parameters

Name	In	Type	Required	Description
source_id	path	string	Yes	Source identifier

cURL

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

TypeScript SDK

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.sync('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",
  "error": null
}

Response 404

{
  "error": "source not found",
  "code": "SOURCE_NOT_FOUND",
  "status": 404
}

Error Code	Title	Description	Resolution
SOURCE_NOT_FOUND	Source not found	No source exists with the requested source_id	Call client.run.sources.list() and choose a valid source_id

Response 503

{
  "error": "sync could not be started",
  "code": "SYNC_START_FAILED",
  "status": 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