{"openapi":"3.1.0","info":{"title":"CosmosID Tracker API — Jona MBL","version":"1.0.0","description":"Read-only access to Jona MBL's orders, outbound kit shipments and received samples.\n\n- **Auth** — POST `username` + `password` to `/v1/auth/token`, then send `Authorization: Bearer <access_token>`. Access tokens last 1 hour; renew with the refresh token (30 days) instead of re-sending the password.\n- **Rate limit** — 100 requests/minute (`RateLimit-*` headers on every response).\n- **Scope** — your token only ever returns Jona MBL data; anything else returns `404`.\n- **Freshness** — orders are near real-time; outbound and inbound sync every 30 minutes (see each record's `synced_at`).\n- **Support** — quote the `X-Request-Id` response header."},"servers":[{"url":"https://tracker-api-jona-mbl.cosmosid.com/v1","description":"Jona MBL production"}],"tags":[{"name":"Authorization","description":"Obtain an access token."},{"name":"Orders","description":"All the orders placed by Jona MBL."},{"name":"Outbound","description":"Kits shipped to your customers."},{"name":"Inbound","description":"Samples received and processed at CMBio."}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"The `access_token` returned by /v1/auth/token."}},"schemas":{"TokenRequest":{"type":"object","description":"Either username+password, or a refresh token.","properties":{"grant_type":{"type":"string","enum":["password","refresh_token"],"default":"password","description":"`password` with username+password for a first token; `refresh_token` with refresh_token to renew."},"username":{"type":["string","null"],"description":"Required for the password grant."},"password":{"type":["string","null"],"description":"Required for the password grant."},"refresh_token":{"type":["string","null"],"description":"Required for the refresh_token grant."}}},"TokenResponse":{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string","examples":["Bearer"]},"expires_in":{"type":"integer","examples":[3600],"description":"Access-token lifetime in seconds (1 hour)."},"refresh_token":{"type":"string","description":"Use this to renew. ROTATED on every use — always store the new value returned here and discard the old one."},"refresh_token_expires_in":{"type":"integer","examples":[2592000],"description":"Refresh-token lifetime in seconds (30 days)."},"scope":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}}}}},"OAuthError":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}}},"OrderListItem":{"type":"object","properties":{"id":{"type":"string"},"order_number":{"type":"string"},"status":{"type":"string"},"order_date":{"type":["string","null"],"format":"date-time","examples":["2026-07-22T16:02:11Z"]},"customer_name":{"type":["string","null"]},"customer_email":{"type":["string","null"]},"sku":{"type":["string","null"]},"item_name":{"type":["string","null"]},"quantity":{"type":["integer","null"]},"ship_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"updated_at":{"type":["string","null"],"format":"date-time","examples":["2026-07-22T16:02:11Z"]}}},"Order":{"type":"object","properties":{"id":{"type":"string"},"order_number":{"type":"string"},"status":{"type":"string"},"order_date":{"type":["string","null"],"format":"date-time","examples":["2026-07-22T16:02:11Z"]},"created_at":{"type":["string","null"],"format":"date-time","examples":["2026-07-22T16:02:11Z"]},"updated_at":{"type":["string","null"],"format":"date-time","examples":["2026-07-22T16:02:11Z"]},"customer":{"type":"object","properties":{"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]}}},"ship_to":{"type":"object","properties":{"line1":{"type":["string","null"]},"line2":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":["string","null"]}}},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":["string","null"]},"name":{"type":["string","null"]},"quantity":{"type":["integer","null"]}}}},"shipping":{"type":"object","properties":{"carrier":{"type":["string","null"]},"service":{"type":["string","null"]},"ship_by_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"ship_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"weight":{"type":["string","null"]},"gift":{"type":"boolean"}}},"customer_notes":{"type":["string","null"]},"links":{"type":"object","properties":{"outbound":{"type":["string","null"]},"inbound":{"type":["string","null"]}}}}},"OrderList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderListItem"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"},"has_more":{"type":"boolean"}}}}},"OutboundListItem":{"type":"object","properties":{"id":{"type":"string"},"order_number":{"type":["string","null"]},"master_barcode":{"type":["string","null"],"description":"Always null for this tenant: no Biomarker tab exists, so no master barcode is available."},"barcode":{"type":["string","null"]},"ship_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"sku":{"type":["string","null"]},"sample_type":{"type":["string","null"]},"outbound_tracking":{"type":["string","null"]},"return_tracking":{"type":["string","null"]},"carrier":{"type":["string","null"]},"received_by_client":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"sample_received_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"synced_at":{"type":["string","null"],"format":"date-time","examples":["2026-07-22T16:02:11Z"]}}},"Outbound":{"type":"object","properties":{"id":{"type":"string"},"order_number":{"type":["string","null"]},"master_barcode":{"type":["string","null"],"description":"Always null for this tenant: no Biomarker tab exists, so no master barcode is available."},"barcode":{"type":["string","null"]},"ship_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"sku":{"type":["string","null"]},"sample_type":{"type":["string","null"]},"kit":{"type":"object","properties":{"outbound_tracking":{"type":["string","null"]},"return_tracking":{"type":["string","null"]},"carrier":{"type":["string","null"]},"shipping_region":{"type":["string","null"]},"received_by_client":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"days_in_transit":{"type":["integer","null"]},"kit_replacement":{"type":["string","null"]}}},"sample":{"type":"object","properties":{"sample_received_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"received_at_cid":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"due_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"updated_due_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"reseq_decision_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]}}},"notes":{"type":["string","null"]},"linked_order_id":{"type":["string","null"]},"synced_at":{"type":["string","null"],"format":"date-time","examples":["2026-07-22T16:02:11Z"]},"links":{"type":"object","properties":{"order":{"type":["string","null"]},"inbound":{"type":["string","null"]}}}}},"OutboundList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OutboundListItem"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"},"has_more":{"type":"boolean"}}}}},"InboundListItem":{"type":"object","properties":{"id":{"type":"string"},"order_number":{"type":["string","null"]},"master_barcode":{"type":["string","null"],"description":"Always null for this tenant: no Biomarker tab exists, so no master barcode is available."},"barcode":{"type":["string","null"]},"received_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"sample_type":{"type":["string","null"]},"processing_type":{"type":["string","null"]},"cid_status":{"type":["string","null"]},"due_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"delivery_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"synced_at":{"type":["string","null"],"format":"date-time","examples":["2026-07-22T16:02:11Z"]}}},"Inbound":{"type":"object","properties":{"id":{"type":"string"},"order_number":{"type":["string","null"]},"master_barcode":{"type":["string","null"],"description":"Always null for this tenant: no Biomarker tab exists, so no master barcode is available."},"barcode":{"type":["string","null"]},"sample":{"type":"object","properties":{"sample_type":{"type":["string","null"]},"processing_type":{"type":["string","null"]},"collection_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"received_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"sku":{"type":["string","null"]}}},"processing":{"type":"object","properties":{"tat":{"type":["string","null"]},"depth":{"type":["string","null"]},"cid_status":{"type":["string","null"]},"client_status":{"type":["string","null"]},"due_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"updated_due_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"delivery_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"client_delivery_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]},"reseq_decision_date":{"type":["string","null"],"format":"date","examples":["2026-07-22"]}}},"notes":{"type":["string","null"]},"linked_order_id":{"type":["string","null"]},"synced_at":{"type":["string","null"],"format":"date-time","examples":["2026-07-22T16:02:11Z"]},"links":{"type":"object","properties":{"order":{"type":["string","null"]},"outbound":{"type":["string","null"]}}}}},"InboundList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InboundListItem"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}},"paths":{"/auth/token":{"post":{"tags":["Authorization"],"summary":"Get an access token (password or refresh_token grant)","description":"Returns a Bearer access token valid for 3600 seconds (1 hour), plus a refresh token valid for 30 days.\n\n**First call** — `grant_type=password` with your `username` and `password`.\n\n**Renewing** — `grant_type=refresh_token` with the `refresh_token` you were last given. You do not need to re-send the password.\n\n**Refresh tokens rotate.** Each renewal returns a NEW refresh token and invalidates the one you presented, so always persist the new value. Presenting an already-used refresh token is treated as a leak: every refresh token for that user is revoked and you must sign in with the password again.\n\nLimited to 10 requests per minute.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}}},"responses":{"200":{"description":"A new access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"400":{"description":"Malformed request or unsupported grant type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"401":{"description":"Invalid username or password. Returned identically for an unknown user, a wrong password, and a deactivated user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"429":{"description":"Too many token requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}}}}},"/orders":{"get":{"tags":["Orders"],"summary":"List orders","parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"page_size","in":"query","required":false,"description":"Records per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"status","in":"query","required":false,"description":"Fulfilment status, e.g. shipped or awaiting_shipment.","schema":{"type":"string"}},{"name":"order_number","in":"query","required":false,"description":"Exact, case-insensitive match.","schema":{"type":"string"}},{"name":"customer_email","in":"query","required":false,"description":"Exact, case-insensitive match.","schema":{"type":"string"}},{"name":"order_date_from","in":"query","required":false,"description":"Inclusive lower bound.","schema":{"type":"string","format":"date"}},{"name":"order_date_to","in":"query","required":false,"description":"Inclusive upper bound.","schema":{"type":"string","format":"date"}},{"name":"updated_since","in":"query","required":false,"description":"Records changed since this time — for incremental sync.","schema":{"type":"string","format":"date-time"}},{"name":"q","in":"query","required":false,"description":"Contains match on order number, customer name, or customer email.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"order_date, updated_at or order_number; prefix with - for descending.","schema":{"type":"string","default":"-order_date"}}],"responses":{"200":{"description":"A page of orders.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderList"}}}},"400":{"description":"Invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope, or wrong tenant hostname.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (100 requests per minute).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}":{"get":{"tags":["Orders"],"summary":"Get one order","description":"The id may be the API id or the order number.","parameters":[{"name":"id","in":"path","required":true,"description":"Order id or order number.","schema":{"type":"string"}}],"responses":{"200":{"description":"The order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"Invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope, or wrong tenant hostname.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such order within your scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (100 requests per minute).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/outbound":{"get":{"tags":["Outbound"],"summary":"List outbound kit shipments","parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"page_size","in":"query","required":false,"description":"Records per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"order_number","in":"query","required":false,"description":"Exact, case-insensitive match.","schema":{"type":"string"}},{"name":"master_barcode","in":"query","required":false,"description":"Accepted, but this tenant has no master barcodes, so it always matches nothing.","schema":{"type":"string"}},{"name":"barcode","in":"query","required":false,"description":"Exact, case-insensitive match on the sample barcode.","schema":{"type":"string"}},{"name":"tracking","in":"query","required":false,"description":"Exact match against outbound OR return tracking.","schema":{"type":"string"}},{"name":"ship_date_from","in":"query","required":false,"description":"Inclusive lower bound.","schema":{"type":"string","format":"date"}},{"name":"ship_date_to","in":"query","required":false,"description":"Inclusive upper bound.","schema":{"type":"string","format":"date"}},{"name":"q","in":"query","required":false,"description":"Contains match across order number, barcodes and tracking.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"ship_date or synced_at; prefix with - for descending.","schema":{"type":"string","default":"-ship_date"}}],"responses":{"200":{"description":"A page of shipments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundList"}}}},"400":{"description":"Invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope, or wrong tenant hostname.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (100 requests per minute).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/outbound/{id}":{"get":{"tags":["Outbound"],"summary":"Get one outbound shipment","description":"The id may be the API id or the barcode.","parameters":[{"name":"id","in":"path","required":true,"description":"Outbound id or barcode.","schema":{"type":"string"}}],"responses":{"200":{"description":"The shipment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Outbound"}}}},"400":{"description":"Invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope, or wrong tenant hostname.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such shipment within your scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (100 requests per minute).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inbound":{"get":{"tags":["Inbound"],"summary":"List received samples","parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"page_size","in":"query","required":false,"description":"Records per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"order_number","in":"query","required":false,"description":"Exact, case-insensitive match.","schema":{"type":"string"}},{"name":"master_barcode","in":"query","required":false,"description":"Accepted, but this tenant has no master barcodes, so it always matches nothing.","schema":{"type":"string"}},{"name":"barcode","in":"query","required":false,"description":"Exact, case-insensitive match on the sample barcode.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"CID status.","schema":{"type":"string"}},{"name":"received_from","in":"query","required":false,"description":"Inclusive lower bound.","schema":{"type":"string","format":"date"}},{"name":"received_to","in":"query","required":false,"description":"Inclusive upper bound.","schema":{"type":"string","format":"date"}},{"name":"q","in":"query","required":false,"description":"Contains match across order number and barcodes.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"received_date or synced_at; prefix with - for descending. (due_date is a sheet value, not an indexed column, so it is not sortable.)","schema":{"type":"string","default":"-received_date"}}],"responses":{"200":{"description":"A page of samples.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundList"}}}},"400":{"description":"Invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope, or wrong tenant hostname.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (100 requests per minute).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inbound/{id}":{"get":{"tags":["Inbound"],"summary":"Get one received sample","description":"The id may be the API id or the barcode.","parameters":[{"name":"id","in":"path","required":true,"description":"Inbound id or barcode.","schema":{"type":"string"}}],"responses":{"200":{"description":"The sample.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inbound"}}}},"400":{"description":"Invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope, or wrong tenant hostname.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such sample within your scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (100 requests per minute).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}