本文へスキップ
CargoDuo logoCargoDuo
料金

このドキュメントは現在、英語版のみです。

開発者向けドキュメントAPI referenceProjects

Pack a project

Packs the project's vehicles and items exactly like POST /v1/pack: same price, credit reservation, limits, Idempotency-Key, ?wait= and job.

POSThttps://runner.cargoduo.com/v1/projects/{id}/pack

When the job succeeds its plan is saved into the project, which then opens in the app with that plan. If the project changed while the job ran, the plan stays on the job only (warning project_not_saved). Result ids are the project's: vehicle_id is the slot id (pv_…), item_id the item id (item_…).

認証

Bearer API キー(必要なスコープ)pack:writeresources:write詳細を見る

パスパラメーター

名前型必須説明
idstring必須
string
はい

Project id (prj_…).

クエリパラメーター

名前型必須説明
waitinteger
integer
いいえ

Seconds to hold the response for the job to finish. Finished in time: 200 with the result inlined. Otherwise: 202.

デフォルト 00–60

ヘッダーパラメーター

名前型必須説明
Idempotency-Keystring
string
いいえ

Any unique string, such as a UUID or your order id. The same key within 24 h returns the original job instead of creating and charging a new one.

≤ 128 chars

ボディパラメーター

application/json
名前型必須説明
referencestring
string
いいえ

Your reference, echoed on the job. Defaults to the project name.

≤ 128 chars
optionsProjectPackOptions
ProjectPackOptions
いいえ

Run options. Every field is optional.

リクエストの例

curl -X POST "https://runner.cargoduo.com/v1/projects/prj_3051/pack" \
  -H "Authorization: Bearer $CARGODUO_API_KEY" \
  -H "Idempotency-Key: order-1042-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-1042"
  }'

レスポンスの例

202 Accepted · Job
{
  "id": "job_4bK9mT2xQe7LpW1zRc8VdN3f",
  "object": "job",
  "status": "queued",
  "reference": "order-1042",
  "source": "api",
  "project_id": "prj_3051",
  "created_at": "2026-10-19T09:12:03Z",
  "started_at": null,
  "finished_at": null,
  "progress": {
    "stage": "queued",
    "vehicles_done": 0,
    "placed_items": 0
  },
  "summary": {
    "items_requested": 58,
    "items_placed": 0,
    "items_unplaced": 0,
    "vehicles_used": 0,
    "total_weight": 0,
    "volume_utilization": 0,
    "queue_ms": 0,
    "compute_ms": 0
  },
  "cost": {
    "credits": 0,
    "reserved_credits": 1.11,
    "rate_card_version": 1,
    "breakdown": {
      "base": 0,
      "vehicles": 0,
      "compute": 0,
      "large_load": 0
    }
  },
  "error": null,
  "warnings": [],
  "result_url": "https://runner.cargoduo.com/v1/jobs/job_4bK9mT2xQe7LpW1zRc8VdN3f/result",
  "pdf_url": "",
  "expires_at": "2026-11-02T09:12:03Z"
}

レスポンス

  • 200OKJob finished within ?wait, result inlined. Also an idempotent replay of a finished job.
    名前型必須説明
    idstring必須
    string
    はい

    Job id (job_…).

    objectstring必須
    string
    はい

    Always job.

    job
    statusstring必須
    string
    はい

    queued → running → succeeded | failed | canceled.

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    いいえ

    Your reference from the request.

    sourcestring
    string
    いいえ

    Where the job was created.

    apiplayground
    project_idstring
    string
    いいえ

    The project (prj_…) a POST /v1/projects/{id}/pack job saves its plan into. Absent on other jobs.

    created_atstring必須
    string
    はい

    RFC 3339 timestamp.

    started_atstring | null
    string | null
    いいえ

    When computing started (RFC 3339) or null.

    finished_atstring | null
    string | null
    いいえ

    When the job ended (RFC 3339) or null.

    progressJobProgress
    JobProgress
    いいえ

    Live progress while queued/running.

    summaryJobSummary
    JobSummary
    いいえ

    Counts and timings.

    costJobCost
    JobCost
    いいえ

    Credits charged (final once the job ended) and the reservation held while it ran.

    errorJobError | null
    JobError | null
    いいえ

    Why the job failed or was canceled; null otherwise.

    warningsWarning[]
    Warning[]
    いいえ

    Non-blocking remarks about the request (also repeated in the result).

    result_urlstring
    string
    いいえ

    GET this URL for the full result once status is succeeded.

    pdf_urlstring
    string
    いいえ

    A browser link that renders the load plan as a PDF (3D views + loading steps). Valid until expires_at. Empty after expiry.

    expires_atstring
    string
    いいえ

    When the request/result bodies and the PDF link are deleted (RFC 3339). Job metadata and charges are kept.

    resultResult
    Result
    いいえ

    The full result, inlined only when requested (?include=result) or when POST /v1/pack?wait= finished in time.

  • 202AcceptedJob accepted (queued or running).
    名前型必須説明
    idstring必須
    string
    はい

    Job id (job_…).

    objectstring必須
    string
    はい

    Always job.

    job
    statusstring必須
    string
    はい

    queued → running → succeeded | failed | canceled.

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    いいえ

    Your reference from the request.

    sourcestring
    string
    いいえ

    Where the job was created.

    apiplayground
    project_idstring
    string
    いいえ

    The project (prj_…) a POST /v1/projects/{id}/pack job saves its plan into. Absent on other jobs.

    created_atstring必須
    string
    はい

    RFC 3339 timestamp.

    started_atstring | null
    string | null
    いいえ

    When computing started (RFC 3339) or null.

    finished_atstring | null
    string | null
    いいえ

    When the job ended (RFC 3339) or null.

    progressJobProgress
    JobProgress
    いいえ

    Live progress while queued/running.

    summaryJobSummary
    JobSummary
    いいえ

    Counts and timings.

    costJobCost
    JobCost
    いいえ

    Credits charged (final once the job ended) and the reservation held while it ran.

    errorJobError | null
    JobError | null
    いいえ

    Why the job failed or was canceled; null otherwise.

    warningsWarning[]
    Warning[]
    いいえ

    Non-blocking remarks about the request (also repeated in the result).

    result_urlstring
    string
    いいえ

    GET this URL for the full result once status is succeeded.

    pdf_urlstring
    string
    いいえ

    A browser link that renders the load plan as a PDF (3D views + loading steps). Valid until expires_at. Empty after expiry.

    expires_atstring
    string
    いいえ

    When the request/result bodies and the PDF link are deleted (RFC 3339). Job metadata and charges are kept.

    resultResult
    Result
    いいえ

    The full result, inlined only when requested (?include=result) or when POST /v1/pack?wait= finished in time.

  • 400Bad requestinvalid_jsonidempotency_key_invalid
    • invalid_jsonThe body is not valid JSON or a field has the wrong type.
    • idempotency_key_invalidThe Idempotency-Key header is longer than 128 characters.
    名前型必須説明
    errorErrorBody必須
    ErrorBody
    はい
    すべてのエラーコード
  • 401Unauthorizedunauthorizedkey_revokedkey_expired
    • unauthorizedMissing, malformed or unknown API key.
    • key_revokedThe key was revoked.
    • key_expiredThe key passed its expiry date.
    名前型必須説明
    errorErrorBody必須
    ErrorBody
    はい
    すべてのエラーコード
  • 402Payment requiredinsufficient_credits
    • insufficient_creditsAvailable credits do not cover the smallest possible run of this job.
    名前型必須説明
    errorErrorBody必須
    ErrorBody
    はい
    すべてのエラーコード
  • 403Forbiddenip_not_allowedsubscription_inactiveaccount_inactivescope_missing
    • ip_not_allowedThe calling IP is not on the key's allowlist.
    • subscription_inactiveThe organization has no active subscription that includes the API.
    • account_inactiveThe organization is suspended, or has no owner whose account is active.
    • scope_missingThe key lacks a scope this endpoint needs.
    名前型必須説明
    errorErrorBody必須
    ErrorBody
    はい
    すべてのエラーコード
  • 404Not foundproject_not_found
    • project_not_foundNo project with this id in your organization.
    名前型必須説明
    errorErrorBody必須
    ErrorBody
    はい
    すべてのエラーコード
  • 409Conflictproject_busy
    • project_busyThe project is being packed right now (in the app or by another job).
    名前型必須説明
    errorErrorBody必須
    ErrorBody
    はい
    すべてのエラーコード
  • 413Payload too largepayload_too_large
    • payload_too_largeThe request body exceeds 10 MB.
    名前型必須説明
    errorErrorBody必須
    ErrorBody
    はい
    すべてのエラーコード
  • 422Unprocessable entityvalidation_failed
    • validation_failedThe request is well-formed JSON but describes an invalid job. details[] lists every problem.
    名前型必須説明
    errorErrorBody必須
    ErrorBody
    はい
    すべてのエラーコード
  • 429Too many requeststoo_many_jobsrate_limited
    • too_many_jobsThe organization already has the maximum number of queued + running jobs.
    • rate_limitedToo many requests in the current minute, hour or day (per key or per organization), or more than 60 failed authentications per minute from your IP address.
    名前型必須説明
    errorErrorBody必須
    ErrorBody
    はい
    すべてのエラーコード
  • 500Internal server errorinternal_error
    • internal_errorSomething failed on our side.
    名前型必須説明
    errorErrorBody必須
    ErrorBody
    はい
    すべてのエラーコード
  • 503Service unavailableapi_disabled
    • api_disabledThe API is temporarily disabled (maintenance) or switched off for the organization.
    名前型必須説明
    errorErrorBody必須
    ErrorBody
    はい
    すべてのエラーコード