RPC Reference
The Dango client API is an organization-scoped ConnectRPC service (api.v1.Service) for automating enrichment: create and populate a project, track progress, and export the enriched CSV.
Base URL
https://api.dangofish.comAuthentication
Every RPC is authenticated with an organization API key. Send it as a bearer token on each call:
Authorization: Bearer dk_org_...Keys are generated (name + expiration) from your organization settings. The plaintext key (dk_org_...) is shown only once at creation; only its SHA-256 hash is stored. Authorization is by organization membership: a key can only act on projects owned by its own organization.
Common error codes
These codes may be returned by any RPC:
| Code | Meaning |
|---|---|
Unauthenticated | The API key is missing, malformed (not prefixed dk_org_), inactive, or expired. |
PermissionDenied | The target project does not belong to the key’s organization. |
InvalidArgument | A request field is invalid (see per-method notes below). |
FailedPrecondition | The project is in a state that does not allow the operation (see per-method notes below). |
Project lifecycle
There are two ingestion paths into a single enrichment engine:
CreateProject (empty) -- AddActivities (N calls) -- Submit --> enrichment
ImportCSV --------------------------- (auto-sealed) -------/CreateProjectreturns an empty project.AddActivitiesstages rows on an unsealed project.Submitseals the staged lines and starts enrichment. Rows sharing the same designation collapse into one product (one session with an occurrence counter). It is idempotent: re-submitting is a no-op.ImportCSVparses a CSV all-or-nothing, creates the project, and seals it immediately (implicit submit).GetProgressreturns aggregate enrichment counters.ExportCSVreturns a short-lived presigned URL to the enriched CSV.
Project identifiers are short opaque strings (sqids), never raw UUIDs. Pass the value returned by CreateProject or ImportCSV back verbatim to the other methods.
CreateProject
Creates an empty project owned by the caller’s organization.
Request
| Field | Type | Description |
|---|---|---|
name | string | Human-readable project name. |
Response
| Field | Type | Description |
|---|---|---|
project_id | string | Short opaque identifier (sqid). Pass it back verbatim to AddActivities, Submit, GetProgress, and ExportCSV. |
Errors
Unauthenticated: missing or invalid API key.
ImportCSV
Creates a project from a CSV upload and immediately seals it (implicit submit), so enrichment starts at once. Parsing is all-or-nothing: if any row is invalid, the whole import is rejected.
Request
| Field | Type | Description |
|---|---|---|
name | string | Human-readable project name. |
csv | bytes | Raw CSV payload, following the agent import template. |
category_mode | string | One of ademe (default), client, referential. |
Response
| Field | Type | Description |
|---|---|---|
project_id | string | Short opaque identifier (sqid) of the created project. |
Errors
Unauthenticated: missing or invalid API key.InvalidArgument: the CSV is malformed or the payload is too large.
AddActivities
Stages rows on an unsealed project. Each row mirrors the 10-column agent import template. Rows collapse by designation at submit time. Rejected if the project is already sealed.
Request
| Field | Type | Description |
|---|---|---|
project_id | string | The sqid returned by CreateProject or ImportCSV. |
activities | ImportActivity (repeated) | Rows to stage. |
Each ImportActivity has the following fields (all strings). designation is required.
| Field | Type | Description |
|---|---|---|
designation | string | Product designation (required). |
supplier | string | Supplier name. |
unit_price | string | Unit price. |
currency | string | Currency. |
quantity | string | Quantity. |
unit | string | Unit. |
purchase_date | string | Purchase date. |
weight | string | Weight. |
notes | string | Free-form notes. |
category | string | Category. |
Response
| Field | Type | Description |
|---|---|---|
staged | int64 | Total number of staged rows on the project after this call. |
Errors
Unauthenticated: missing or invalid API key.PermissionDenied: the project belongs to another organization.InvalidArgument: a row is invalid (for example, a missing designation).FailedPrecondition: the project is already sealed.
Submit
Seals a project’s staged lines and starts enrichment. Rows sharing the same designation are grouped into one product (one session plus an occurrence counter). Idempotent: re-submitting a sealed project is a no-op.
Request
| Field | Type | Description |
|---|---|---|
project_id | string | The sqid returned by CreateProject or ImportCSV. |
webhook_url | string | Optional. When set, receives a signed POST when enrichment completes. |
Response
| Field | Type | Description |
|---|---|---|
status | string | Project status after submission. |
Errors
Unauthenticated: missing or invalid API key.PermissionDenied: the project belongs to another organization.InvalidArgument: thewebhook_urlis invalid.FailedPrecondition: the project has no staged lines.
GetProgress
Returns aggregate enrichment counters for a project.
Request
| Field | Type | Description |
|---|---|---|
project_id | string | The sqid returned by CreateProject or ImportCSV. |
Response
| Field | Type | Description |
|---|---|---|
status | string | One of pending, enriching, completed. |
total_lines | int64 | Total number of lines in the batch. |
enriched | int64 | Lines successfully enriched. |
in_progress | int64 | Lines currently being enriched. |
failed | int64 | Lines that failed enrichment. |
submitted_at | string | RFC3339 timestamp of submission; empty when not set. |
completed_at | string | RFC3339 timestamp of completion; empty when not set. |
Errors
Unauthenticated: missing or invalid API key.PermissionDenied: the project belongs to another organization.
ExportCSV
Returns a short-lived presigned URL to download the enriched CSV, in the same format as the web export (one row per product plus computed columns).
Request
| Field | Type | Description |
|---|---|---|
project_id | string | The sqid returned by CreateProject or ImportCSV. |
Response
| Field | Type | Description |
|---|---|---|
download_url | string | Presigned download URL (valid for 15 minutes). |
expires_at | string | RFC3339 instant at which the presigned URL stops working. |
Errors
Unauthenticated: missing or invalid API key.PermissionDenied: the project belongs to another organization.FailedPrecondition: the project is not ready for export.