Skip to Content
We are live but in Staging 🎉
PipelinesAPI ReferenceJobs

Jobs — API Reference

Package: dodil.k3.ingest.v1 · Service: IngestService

An ingest job is one execution of one pipeline against one object. The Jobs RPCs let you fire a one-shot ingest, look up a specific job, or list jobs in a bucket with filters. See Core Concepts → IngestJob.

RPCHTTP
TriggerIngestPOST /:bucket/ingest
GetIngestStatusGET /:bucket/ingest/jobs/:job_id
ListIngestJobsGET /:bucket/ingest/jobs

gRPC setup — grpcurl, endpoints, reflection, and field-name casing — is covered once in Conventions → Using gRPC.

TriggerIngest

One-shot ingest of a single object — skips discovery. Useful for testing pipelines, re-ingesting after a change, or piping in an object from an external system without going through the source sync layer.

By default K3 resolves which pipeline to run by matching the object against the bucket’s rules. Pass pipeline_id or rule_id to override.

Request

Resolve pipeline from matching rules:

curl -sS -X POST "https://k3.dev.dodil.io/kb-prod/ingest" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "object": { "bucket": "kb-prod", "key": "contracts/acme-2026.pdf" }
  }'

Force a specific pipeline + per-event option overlay:

curl -sS -X POST "https://k3.dev.dodil.io/kb-prod/ingest" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "object": { "bucket": "kb-prod", "key": "contracts/acme-2026.pdf" },
    "pipelineId": "pipe_a1b2...",
    "options": { "chunk_size": "2000" }
  }'

Response

{
  "job": {
    "jobId": "job_a1b2...",
    "object": { "bucket": "kb-prod", "key": "contracts/acme-2026.pdf" },
    "status": "INGEST_STATUS_PENDING",
    "pipelineId": "pipe_a1b2...",
    "pipelineName": "embed-contracts",
    "pipelineKind": "vector",
    "createdAt": "1716843600000"
  }
}

The response contains the freshly created IngestJob, typically in PENDING or already PROCESSING. Poll GetIngestStatus for terminal state.

The options map on the request is a per-event overlay on top of the pipeline’s stored options — useful for one-off parameter sweeps without modifying the pipeline itself.

GetIngestStatus

Request

curl -sS "https://k3.dev.dodil.io/kb-prod/ingest/jobs/job_a1b2..." \
  -H "Authorization: Bearer $DODIL_TOKEN"

Response

An IngestJob — see Core Concepts → IngestJob for the full set of counters (chunks_created, embeddings_created, rows_written, batches_received, embeddings_written) and per-pipeline-kind semantics.

ListIngestJobs

Filter by status_filter, pipeline_id, or rule_id. Cursor pagination.

Request

All failed jobs:

curl -sS "https://k3.dev.dodil.io/kb-prod/ingest/jobs?status_filter=INGEST_STATUS_FAILED" \
  -H "Authorization: Bearer $DODIL_TOKEN"

Jobs for one pipeline:

curl -sS "https://k3.dev.dodil.io/kb-prod/ingest/jobs?pipeline_id=pipe_a1b2...&page_size=100" \
  -H "Authorization: Bearer $DODIL_TOKEN"

Jobs for one rule:

curl -sS "https://k3.dev.dodil.io/kb-prod/ingest/jobs?rule_id=rule_a1b2..." \
  -H "Authorization: Bearer $DODIL_TOKEN"

Response

{
  "jobs": [
    {
      "jobId": "job_a1b2...",
      "object": { "bucket": "kb-prod", "key": "contracts/acme-2026.pdf" },
      "status": "INGEST_STATUS_COMPLETED",
      "pipelineId": "pipe_a1b2...",
      "pipelineName": "embed-contracts",
      "pipelineKind": "vector",
      "ruleId": "rule_a1b2...",
      "chunksCreated": 47,
      "embeddingsCreated": 47,
      "rowsWritten": 0,
      "createdAt": "1716843600000",
      "updatedAt": "1716843680000",
      "threadId": "thread_a1b2...",
      "vectorStatus": "success",
      "outputSize": 18429,
      "batchesReceived": 5,
      "embeddingsWritten": 47
    }
  ],
  "pagination": { "nextPageToken": "", "totalCount": "1" }
}

See also

SyncOverview