API overview

The CoCoCo console is built on a GraphQL API, and integrations use the same API: an MIS pushing jobs, a web shop creating orders, a dashboard reading production status.

Endpoint

Each tenant has its own host. The API lives on that host:

POST https://<your-tenant-host>/graphql
Content-Type: application/json
Authorization: Bearer <API token>

The request body is standard GraphQL-over-HTTP JSON: query, and optionally variables and operationName.

The tenant is resolved from the host name, so you never pass a tenant ID in the query. A request whose host does not resolve to a tenant is rejected before any GraphQL runs.

The full schema is published as SDL at:

GET https://<your-tenant-host>/graphql/schema

Use it for code generation and editor tooling. The API reference on this site is generated from the same schema.

Authentication

Every request carries a bearer token in the Authorization header. There are two kinds of token, and both work the same way on the wire:

Token	Where to create it	Use it for
Service account token	Console: Service accounts. Create the account, attach the IAM policies it needs, open it and create a token in its API Tokens section.	Integrations and anything long-running. The token represents the integration, not a person, and the account cannot sign in interactively.
Personal token	Console: user menu, API Tokens (/#/api-tokens)	Local scripts and experiments. It carries your own permissions, so treat it like a password.

What a token may do is decided by the IAM policies attached to its account. If a token is missing or lacks a permission, the response carries a top-level GraphQL error (see Errors).

A first call to check that the host is reachable:

curl -s https://<your-tenant-host>/graphql \
  -H "Authorization: Bearer $COCOCO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"query { ping }"}'

{ "data": { "ping": "pong" } }

ping needs no permissions, so it answers even with a bad token. To check the token, ask for something it must be allowed to read. With the job:list permission, this returns the number of jobs; without it, a top-level error:

curl -s https://<your-tenant-host>/graphql \
  -H "Authorization: Bearer $COCOCO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"query { listJobs(first: 1) { totalCount } }"}'

Try queries in the console

Signed in to the console, you have two developer tools (the playground is shown to users whose permissions let them view scripts):

• GraphQL playground at /#/graphql-playground: write and run queries and mutations against your tenant, with a schema explorer and a variables panel. It runs as your signed-in user, with your permissions.
• API docs at /#/docs: guides and a schema reference.

Conventions

The same patterns apply across the whole schema. Core patterns covers each one with examples.

• Types. Entities are named <Entity>State: JobState, ComponentState, OrderState.
• Queries. get<Entity>(id:) fetches one record, get<Entity>By(externalId:) looks one up by your own reference, and list<Entities> returns a paginated connection.
• Mutations. Most are named create<Entity>(input:), update<Entity>(id:, input:), upsert<Entity>(input:) and delete<Entity>, and return a payload with the entity and an errors list.
• IDs. IDs are typed and prefixed, for example job_01M0R249JMETNBM1Z7466MXGZD.
• Enums. Enum values are upper case on the wire (CONFIRMED, DIGITAL_PRINTING).

A typical first query, listing the five jobs due soonest:

query UpcomingJobs {
  listJobs(first: 5, sort: [{ field: DUE_AT, direction: ASC }]) {
    totalCount
    edges {
      node {
        id
        jobNumber
        name
        status
        dueAt
      }
    }
  }
}

Main domains

Domain	Main types	Start with
Production	JobState, JobGroupState, ComponentState, OperationState, MilestoneState	Job management, Components and media
Commerce	CustomerState, EstimateState, OrderState, OrderLineState, InvoiceState	Orders and commerce
Shipping	ShipmentState, CarrierState	Orders and commerce
Files	FileState, ComponentArtworkFileState	Components and media
Materials and purchasing	SubstrateState, WarehouseStockState, WarehouseTransferState, SupplierState, PurchaseOrderState	API reference
Shop floor	WorkCenterState, DeviceState	API reference
Automation	WorkflowState	Workflow automation

Coming from JDF

If you know JDF, most concepts have a direct counterpart. The CoCoCo model is flat: records point at each other by ID instead of nesting inside one ticket.

JDF	CoCoCo
Job ticket (root JDF node)	JobState
Product part / component resource	ComponentState, kind from ComponentKind
Media resource	ComponentState.media (Media), or a substrate record (SubstrateState)
Layout / trim and bleed boxes	ComponentState.layout (ComponentLayout)
RunList / artwork files	ComponentArtworkFileState linking a FileState to a component
Process node	OperationState, kind from OperationKind
Node status	JobStatus, OperationStatus
Device	DeviceState, grouped into a WorkCenterState
Customer info	CustomerState, ContactState, AddressState

Next steps

• Core patterns: pagination, filters, sorting, mutations and errors.
• GraphQL introduction, if GraphQL is new to you.
• API reference: every public query, mutation and type.