{"openapi":"3.1.0","info":{"title":"fabPlane API","version":"1.0.0","description":"Organizations, personal API tokens, shopping carts (BOM with purchase destinations) and team inventory. Errors are `{ error, message? }`. See https://fabplane.com/docs/api."},"servers":[{"url":"https://api.fabplane.com"}],"paths":{"/v1/private/me":{"get":{"operationId":"getMe","summary":"Current principal, email verification state and personal org","tags":["Me"],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"The signed-in principal","content":{"application/json":{"schema":{"type":"object","properties":{"principal":{"type":"object","properties":{"subject":{"type":"string"},"email":{"type":"string"},"userId":{"type":"string"},"handle":{"type":"string"},"displayName":{"type":"string"},"kind":{"type":"string","enum":["human","bot"]},"botOrgId":{"type":"string"}},"required":["subject"]},"bot":{"anyOf":[{"$ref":"#/components/schemas/Bot"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"emailVerified":{"type":"boolean"},"personalOrgId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["principal","email","emailVerified","personalOrgId"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/tokens":{"get":{"operationId":"listTokens","summary":"List personal API tokens","tags":["Tokens"],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"Tokens","content":{"application/json":{"schema":{"type":"object","properties":{"tokens":{"type":"array","items":{"$ref":"#/components/schemas/ApiToken"}}},"required":["tokens"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createToken","summary":"Create a personal API token (the secret is returned once)","tags":["Tokens"],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"expiresInDays":{"type":"integer","minimum":1,"maximum":3650}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"$ref":"#/components/schemas/ApiToken"},"secret":{"type":"string"}},"required":["token","secret"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/tokens/{tokenId}":{"delete":{"operationId":"deleteToken","summary":"Revoke a personal API token","tags":["Tokens"],"parameters":[{"name":"tokenId","in":"path","required":true,"schema":{"type":"string"}}],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"204":{"description":"Revoked"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs":{"get":{"operationId":"listOrgs","summary":"List the caller's orgs (creates the personal org on first use)","tags":["Orgs"],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"Orgs","content":{"application/json":{"schema":{"type":"object","properties":{"orgs":{"type":"array","items":{"$ref":"#/components/schemas/Org"}}},"required":["orgs"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createOrg","summary":"Create an org; the caller becomes its owner","tags":["Orgs"],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"slug":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,38}$"}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"org":{"$ref":"#/components/schemas/Org"}},"required":["org"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/joinable":{"get":{"operationId":"listJoinableOrgs","summary":"Orgs the caller may join through their verified email domain","tags":["Orgs"],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"Joinable orgs","content":{"application/json":{"schema":{"type":"object","properties":{"orgs":{"type":"array","items":{"$ref":"#/components/schemas/OrgSummary"}}},"required":["orgs"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}":{"get":{"operationId":"getOrg","summary":"Get an org the caller belongs to","tags":["Orgs"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"The org","content":{"application/json":{"schema":{"type":"object","properties":{"org":{"$ref":"#/components/schemas/Org"}},"required":["org"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateOrg","summary":"Rename an org or configure domain join (admin)","tags":["Orgs"],"description":"`domainJoin.domain` must equal the caller's verified email domain; public webmail domains and personal orgs are rejected.","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"x-human-only":"partial","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"domainJoin":{"anyOf":[{"type":"object","properties":{"domain":{"type":"string","minLength":3,"maxLength":253},"enabled":{"type":"boolean"}},"required":["domain","enabled"],"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"The updated org","content":{"application/json":{"schema":{"type":"object","properties":{"org":{"$ref":"#/components/schemas/Org"}},"required":["org"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"deleteOrg","summary":"Delete an org and everything in it (owner; not personal orgs)","tags":["Orgs"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"204":{"description":"Deleted"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/join":{"post":{"operationId":"joinOrg","summary":"Join an org through its verified email domain","tags":["Orgs"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"The joined org","content":{"application/json":{"schema":{"type":"object","properties":{"org":{"$ref":"#/components/schemas/Org"}},"required":["org"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/members":{"get":{"operationId":"listMembers","summary":"List org members","tags":["Members"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"Members","content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/Member"}}},"required":["members"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/members/{userId}":{"patch":{"operationId":"updateMember","summary":"Change a member's role (admin; only owners grant or revoke owner)","tags":["Members"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string"}}],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"$ref":"#/components/schemas/Role"}},"required":["role"],"additionalProperties":false}}}},"responses":{"200":{"description":"The updated member","content":{"application/json":{"schema":{"type":"object","properties":{"member":{"$ref":"#/components/schemas/Member"}},"required":["member"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`conflict`: the last owner cannot be demoted"}}},"delete":{"operationId":"removeMember","summary":"Remove a member (admin), or leave the org (self)","tags":["Members"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string"}}],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"204":{"description":"Removed"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`conflict`: the last owner cannot leave"}}}},"/v1/private/orgs/{orgId}/invites":{"get":{"operationId":"listInvites","summary":"List pending invites (admin)","tags":["Invites"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"Pending invites","content":{"application/json":{"schema":{"type":"object","properties":{"invites":{"type":"array","items":{"$ref":"#/components/schemas/Invite"}}},"required":["invites"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createInvite","summary":"Create an invite link (admin). No email is sent.","tags":["Invites"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"role":{"type":"string","enum":["admin","member"]},"expiresInDays":{"type":"integer","minimum":1,"maximum":30}},"additionalProperties":false}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"invite":{"$ref":"#/components/schemas/Invite"}},"required":["invite"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/invites/{inviteId}":{"delete":{"operationId":"revokeInvite","summary":"Revoke a pending invite (admin)","tags":["Invites"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"inviteId","in":"path","required":true,"schema":{"type":"string"}}],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"204":{"description":"Revoked"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/invites/{token}":{"get":{"operationId":"getInvite","summary":"Preview a pending invite by token","tags":["Invites"],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"The invite","content":{"application/json":{"schema":{"type":"object","properties":{"invite":{"$ref":"#/components/schemas/InvitePreview"}},"required":["invite"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/invites/{token}/accept":{"post":{"operationId":"acceptInvite","summary":"Accept an invite (single use; email-bound invites need a matching verified email)","tags":["Invites"],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"The joined org","content":{"application/json":{"schema":{"type":"object","properties":{"org":{"$ref":"#/components/schemas/Org"}},"required":["org"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/destinations":{"get":{"operationId":"listDestinations","summary":"Built-in purchase destinations followed by the org's custom ones","tags":["Destinations"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"Destinations","content":{"application/json":{"schema":{"type":"object","properties":{"destinations":{"type":"array","items":{"$ref":"#/components/schemas/Destination"}}},"required":["destinations"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createDestination","summary":"Add a custom purchase destination (admin), e.g. DigiKey Thailand","tags":["Destinations"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"url":{"type":"string","maxLength":2000},"kind":{"$ref":"#/components/schemas/DestinationKind"},"baseId":{"type":"string","enum":["builtin:jlcpcb","builtin:pcbway","builtin:oshpark","builtin:digikey","builtin:mouser","builtin:lcsc","builtin:arrow","builtin:farnell","builtin:aliexpress","builtin:amazon","builtin:manual"]}},"required":["name","url"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"destination":{"$ref":"#/components/schemas/Destination"}},"required":["destination"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/destinations/{destinationId}":{"delete":{"operationId":"deleteDestination","summary":"Delete a custom destination (admin); its cart items fall back to builtin:manual","tags":["Destinations"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"destinationId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"204":{"description":"Deleted"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/auth/bot/connect":{"post":{"operationId":"startBotConnect","summary":"Start connecting an agent as a bot member (device-code style)","tags":["Bots"],"description":"Anonymous and rate limited. Show `verificationUriComplete` to a human org admin, then poll pollBotConnect.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"clientId":{"type":"string","minLength":1,"maxLength":64},"org":{"type":"string","minLength":1,"maxLength":63},"agentKind":{"type":"string","enum":["openclaw","hermes","fabdesk","ci","other"]}},"required":["name","clientId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Connect codes","content":{"application/json":{"schema":{"type":"object","properties":{"connectCode":{"type":"string"},"userCode":{"type":"string"},"verificationUri":{"type":"string"},"verificationUriComplete":{"type":"string"},"expiresIn":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"interval":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["connectCode","userCode","verificationUri","verificationUriComplete","expiresIn","interval"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"description":"`invalid_client`: clientId is not a first-party client"},"429":{"description":"`rate_limited`"},"503":{"description":"`authentication_unavailable`"}}}},"/v1/auth/bot/token":{"post":{"operationId":"pollBotConnect","summary":"Poll for the bot token (issued once, after approval)","tags":["Bots"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"connectCode":{"type":"string","minLength":1,"maxLength":512}},"required":["connectCode"],"additionalProperties":false}}}},"responses":{"200":{"description":"The bot token (only on the first poll after approval)","content":{"application/json":{"schema":{"type":"object","properties":{"accessToken":{"type":"string"},"tokenType":{"type":"string","const":"bearer"},"bot":{"$ref":"#/components/schemas/Bot"},"org":{"$ref":"#/components/schemas/OrgSummary"}},"required":["accessToken","tokenType","bot","org"]}}}},"400":{"description":"`access_denied`, `expired_token` (expired, unknown or already issued), `invalid_request`"},"428":{"description":"`authorization_pending`"},"429":{"description":"`slow_down` with the new `interval`"}}}},"/v1/private/bots/connect/{userCode}":{"get":{"operationId":"getBotConnectRequest","summary":"Show a pending bot connect request and the orgs you can approve it into","tags":["Bots"],"parameters":[{"name":"userCode","in":"path","required":true,"schema":{"type":"string"}}],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"The request and your admin orgs","content":{"application/json":{"schema":{"type":"object","properties":{"request":{"$ref":"#/components/schemas/BotConnectRequest"},"orgs":{"type":"array","items":{"$ref":"#/components/schemas/OrgSummary"}}},"required":["request","orgs"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/bots/connect/{userCode}/approve":{"post":{"operationId":"approveBotConnect","summary":"Approve a bot into an org you administer (personal orgs allowed)","tags":["Bots"],"parameters":[{"name":"userCode","in":"path","required":true,"schema":{"type":"string"}}],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string","minLength":1,"maxLength":64},"role":{"type":"string","enum":["member","admin"]}},"required":["orgId"],"additionalProperties":false}}}},"responses":{"200":{"description":"The new bot","content":{"application/json":{"schema":{"type":"object","properties":{"bot":{"$ref":"#/components/schemas/Bot"}},"required":["bot"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/bots/connect/{userCode}/deny":{"post":{"operationId":"denyBotConnect","summary":"Deny a bot connect request","tags":["Bots"],"parameters":[{"name":"userCode","in":"path","required":true,"schema":{"type":"string"}}],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"204":{"description":"Denied"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/bots":{"get":{"operationId":"listBots","summary":"List the org's bot accounts (admin)","tags":["Bots"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"Bots","content":{"application/json":{"schema":{"type":"object","properties":{"bots":{"type":"array","items":{"$ref":"#/components/schemas/Bot"}}},"required":["bots"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createBot","summary":"Create a bot directly (admin); the token is shown once","tags":["Bots"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"role":{"type":"string","enum":["member","admin"]},"agentKind":{"type":"string","enum":["openclaw","hermes","fabdesk","ci","other"]}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"bot":{"$ref":"#/components/schemas/Bot"},"token":{"type":"string"}},"required":["bot","token"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/bots/{botId}/tokens":{"post":{"operationId":"rotateBotToken","summary":"Issue a new bot token and revoke the previous ones (admin)","tags":["Bots"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"botId","in":"path","required":true,"schema":{"type":"string"}}],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"201":{"description":"The new token (shown once)","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"}},"required":["token"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/bots/{botId}":{"delete":{"operationId":"deleteBot","summary":"Remove a bot and revoke its tokens (admin)","tags":["Bots"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"botId","in":"path","required":true,"schema":{"type":"string"}}],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"204":{"description":"Removed"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/carts":{"get":{"operationId":"listCarts","summary":"List carts; filter by tagged repo (normalized) or client project id","tags":["Carts"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"repo","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":500}},{"name":"projectId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"Carts","content":{"application/json":{"schema":{"type":"object","properties":{"carts":{"type":"array","items":{"$ref":"#/components/schemas/CartSummary"}}},"required":["carts"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createCart","summary":"Create a cart (shopping list / BOM)","tags":["Carts"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"repos":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"projectId":{"type":"string","minLength":1,"maxLength":200},"notes":{"type":"string","maxLength":4000},"fabDestinationId":{"type":"string","minLength":1,"maxLength":64}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"cart":{"$ref":"#/components/schemas/Cart"}},"required":["cart"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/carts/{cartId}":{"get":{"operationId":"getCart","summary":"Get a cart with its items grouped by destination","tags":["Carts"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"cartId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"The cart","content":{"application/json":{"schema":{"type":"object","properties":{"cart":{"$ref":"#/components/schemas/Cart"}},"required":["cart"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateCart","summary":"Update cart metadata","tags":["Carts"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"cartId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"repos":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"projectId":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"notes":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}]},"fabDestinationId":{"type":"string","minLength":1,"maxLength":64}},"additionalProperties":false}}}},"responses":{"200":{"description":"The updated cart","content":{"application/json":{"schema":{"type":"object","properties":{"cart":{"$ref":"#/components/schemas/Cart"}},"required":["cart"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"deleteCart","summary":"Delete a cart","tags":["Carts"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"cartId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"204":{"description":"Deleted"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/carts/{cartId}/move":{"post":{"operationId":"moveCart","summary":"Move a cart to another org the caller belongs to","tags":["Carts"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"cartId","in":"path","required":true,"schema":{"type":"string"}}],"x-human-only":true,"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"targetOrgId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["targetOrgId"],"additionalProperties":false}}}},"responses":{"200":{"description":"The cart in its new org","content":{"application/json":{"schema":{"type":"object","properties":{"cart":{"$ref":"#/components/schemas/Cart"}},"required":["cart"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/carts/{cartId}/items":{"post":{"operationId":"addCartItems","summary":"Append items; items without destinationId follow the cart's fab destination","tags":["Carts"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"cartId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"minItems":1,"maxItems":500,"type":"array","items":{"$ref":"#/components/schemas/CartItemInput"}}},"required":["items"],"additionalProperties":false}}}},"responses":{"201":{"description":"The added items","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CartItem"}}},"required":["items"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"put":{"operationId":"replaceCartItems","summary":"Replace every item (BOM sync)","tags":["Carts"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"cartId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"maxItems":2000,"type":"array","items":{"$ref":"#/components/schemas/CartItemInput"}},"source":{"type":"string","minLength":1,"maxLength":80}},"required":["items"],"additionalProperties":false}}}},"responses":{"200":{"description":"The cart after replacement","content":{"application/json":{"schema":{"type":"object","properties":{"cart":{"$ref":"#/components/schemas/Cart"}},"required":["cart"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/carts/{cartId}/items/{itemId}":{"patch":{"operationId":"updateCartItem","summary":"Update one item (destination, quantity, status, …)","tags":["Carts"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"cartId","in":"path","required":true,"schema":{"type":"string"}},{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["pcb","part","other"]},"mpn":{"type":"string","maxLength":200},"manufacturer":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":2000},"value":{"type":"string","maxLength":200},"footprint":{"type":"string","maxLength":300},"refs":{"maxItems":500,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"quantity":{"type":"integer","minimum":0,"maximum":100000000},"destinationId":{"type":"string","minLength":1,"maxLength":64},"sku":{"type":"string","maxLength":200},"url":{"type":"string","maxLength":2000},"unitPrice":{"type":"number","minimum":0,"maximum":100000000},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"status":{"type":"string","enum":["needed","ordered","received"]},"notes":{"type":"string","maxLength":4000},"inventoryItemId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"The updated item","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/CartItem"}},"required":["item"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"deleteCartItem","summary":"Remove one item","tags":["Carts"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"cartId","in":"path","required":true,"schema":{"type":"string"}},{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"204":{"description":"Deleted"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/carts/{cartId}/export.csv":{"get":{"operationId":"exportCartCsv","summary":"Export the cart as CSV, optionally for one destination","tags":["Carts"],"description":"Columns: destination (name), kind (item kind), mpn, manufacturer, description, refs (comma-joined), quantity, sku, url, unitPrice, currency, status, notes.","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"cartId","in":"path","required":true,"schema":{"type":"string"}},{"name":"destinationId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"CSV","content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/inventory":{"get":{"operationId":"listInventory","summary":"Search inventory (newest first, cursor paged)","tags":["Inventory"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"category","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"location","in":"query","required":false,"schema":{"type":"string","maxLength":300}},{"name":"tag","in":"query","required":false,"schema":{"type":"string","maxLength":64}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":200}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"A page of items","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InventoryItem"}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["items","nextCursor"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createInventoryItem","summary":"Add an item (JSON, or multipart with `item` JSON and `image` files); upserts by externalId","tags":["Inventory"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItemInput"}},"multipart/form-data":{"schema":{"type":"object","required":["item"],"properties":{"item":{"type":"string","description":"JSON-encoded InventoryItemInput"},"image":{"type":"array","items":{"type":"string","format":"binary"},"maxItems":10}}}}}},"responses":{"200":{"description":"Updated the item with the same (source, externalId)","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/InventoryItem"}},"required":["item"]}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/InventoryItem"}},"required":["item"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"413":{"description":"`payload_too_large`: an image is over 10 MiB"},"415":{"description":"`unsupported_media_type`: image type not accepted"},"501":{"description":"`server_ai_unavailable` when `serverAiProcessing: true`; nothing is stored"},"503":{"description":"`storage_unavailable`: images were sent but object storage is not configured"}}}},"/v1/private/orgs/{orgId}/inventory/bulk":{"post":{"operationId":"bulkUpsertInventory","summary":"Create or update up to 500 items, matched by (source, externalId)","tags":["Inventory"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"minItems":1,"maxItems":500,"type":"array","items":{"$ref":"#/components/schemas/InventoryItemInput"}}},"required":["items"],"additionalProperties":false}}}},"responses":{"200":{"description":"The upserted items in input order","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InventoryItem"}},"created":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"updated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["items","created","updated"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"501":{"description":"`server_ai_unavailable` when `serverAiProcessing: true`; nothing is stored"}}}},"/v1/private/orgs/{orgId}/inventory/photo-queue":{"get":{"operationId":"listPhotoQueue","summary":"Items still waiting for a product photo, with queue counts","tags":["Inventory photo queue"],"description":"`include=available` (default) lists claimable items: no images, status queued, lease absent or expired. `include=all` lists every imageless item, including leased and skipped ones. Ordered by attempts, then age.","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":300}},{"name":"include","in":"query","required":false,"schema":{"type":"string","enum":["available","all"]}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"A page of queue items","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PhotoQueueItem"}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"counts":{"$ref":"#/components/schemas/PhotoQueueCounts"}},"required":["items","nextCursor","counts"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/inventory/photo-queue/claim":{"post":{"operationId":"claimPhotoQueue","summary":"Lease available items for a photo-search worker","tags":["Inventory photo queue"],"description":"Atomic (FOR UPDATE SKIP LOCKED): concurrent claims never return the same item. Increments attempts; fewest attempts, then oldest, first.","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":25},"leaseSeconds":{"type":"integer","minimum":60,"maximum":3600},"worker":{"type":"string","minLength":1,"maxLength":80}},"additionalProperties":false}}}},"responses":{"200":{"description":"The leased items (possibly empty) and the lease expiry","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ClaimedPhotoQueueItem"}},"leaseUntil":{"type":"string"}},"required":["items","leaseUntil"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/inventory/{itemId}/photo-queue/release":{"post":{"operationId":"releasePhotoQueueItem","summary":"Give an item back: retry later, or mark that no photo was found","tags":["Inventory photo queue"],"description":"`retry` clears the lease and keeps the item queued. `not_found` marks it skipped (it leaves the queue) and stores the note. Workers pass the `leaseToken` from their claim; without it only an unleased item can be released. 409 `conflict` when the item is leased under a different token (the lease expired and another worker reclaimed it).","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["retry","not_found"]},"note":{"type":"string","maxLength":500},"leaseToken":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["outcome"],"additionalProperties":false}}}},"responses":{"200":{"description":"The item's queue state","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/PhotoQueueItem"}},"required":["item"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`conflict`: leased by another worker (or the token no longer matches)"}}}},"/v1/private/orgs/{orgId}/inventory/{itemId}/photo-queue/requeue":{"post":{"operationId":"requeuePhotoQueueItem","summary":"Put a skipped item back in the queue with zero attempts (admin)","tags":["Inventory photo queue"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"The item's queue state","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/PhotoQueueItem"}},"required":["item"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/inventory/{itemId}":{"get":{"operationId":"getInventoryItem","summary":"Get one inventory item","tags":["Inventory"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"The item","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/InventoryItem"}},"required":["item"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateInventoryItem","summary":"Update fields of an inventory item","tags":["Inventory"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"mpn":{"type":"string","maxLength":200},"manufacturer":{"type":"string","maxLength":200},"sku":{"type":"string","maxLength":200},"category":{"type":"string","maxLength":120},"description":{"type":"string","maxLength":4000},"quantity":{"type":"integer","minimum":0,"maximum":1000000000},"unit":{"type":"string","minLength":1,"maxLength":32},"location":{"type":"string","maxLength":300},"tags":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"attributes":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":100},"additionalProperties":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"source":{"type":"string","minLength":1,"maxLength":80},"externalId":{"type":"string","minLength":1,"maxLength":200},"serverAiProcessing":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"The updated item","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/InventoryItem"}},"required":["item"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`conflict`: another item already has this (source, externalId)"},"501":{"description":"`server_ai_unavailable` when `serverAiProcessing: true`; nothing is stored"}}},"delete":{"operationId":"deleteInventoryItem","summary":"Delete an item and its images","tags":["Inventory"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"204":{"description":"Deleted"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/private/orgs/{orgId}/inventory/{itemId}/adjust":{"post":{"operationId":"adjustInventory","summary":"Atomically add to or take from the quantity","tags":["Inventory"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"delta":{"type":"integer","minimum":-1000000000,"maximum":1000000000},"reason":{"type":"string","maxLength":500}},"required":["delta"],"additionalProperties":false}}}},"responses":{"200":{"description":"The updated item","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/InventoryItem"}},"required":["item"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`conflict`: the quantity would drop below zero"}}}},"/v1/private/orgs/{orgId}/inventory/{itemId}/images":{"post":{"operationId":"uploadInventoryImage","summary":"Upload a photo (multipart `image`, or a raw image body)","tags":["Inventory"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","format":"binary"},"source":{"type":"string","maxLength":80,"description":"Where the photo came from, e.g. user or web"},"sourceUrl":{"type":"string","maxLength":2000,"description":"http(s) page the photo was found on"}}}},"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"image/gif":{"schema":{"type":"string","format":"binary"}},"image/heic":{"schema":{"type":"string","format":"binary"}},"image/heif":{"schema":{"type":"string","format":"binary"}}}},"responses":{"201":{"description":"Stored","content":{"application/json":{"schema":{"type":"object","properties":{"image":{"$ref":"#/components/schemas/InventoryImage"}},"required":["image"]}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"description":"`conflict`: the item already has 10 images"},"413":{"description":"`payload_too_large`: over 10 MiB"},"415":{"description":"`unsupported_media_type`"},"503":{"description":"`storage_unavailable`"}}}},"/v1/private/orgs/{orgId}/inventory/{itemId}/images/{imageId}":{"get":{"operationId":"getInventoryImage","summary":"Redirect to a 15-minute signed image URL","tags":["Inventory"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}},{"name":"imageId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"302":{"description":"Redirect to the signed URL"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"description":"`storage_unavailable`"}}},"delete":{"operationId":"deleteInventoryImage","summary":"Delete one image","tags":["Inventory"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}},{"name":"imageId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"204":{"description":"Deleted"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"description":"`storage_unavailable`"}}}}},"components":{"schemas":{"Bot":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"name":{"type":"string"},"agentKind":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"type":"string","enum":["owner","admin","member"]},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"lastUsedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","orgId","name","agentKind","role","createdBy","createdAt","lastUsedAt"]},"ApiToken":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"},"createdAt":{"type":"string"},"lastUsedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","prefix","createdAt","lastUsedAt","expiresAt"]},"Org":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"personal":{"type":"boolean"},"role":{"$ref":"#/components/schemas/Role"},"memberCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"domainJoin":{"anyOf":[{"type":"object","properties":{"domain":{"type":"string"},"enabled":{"type":"boolean"}},"required":["domain","enabled"]},{"type":"null"}]},"createdAt":{"type":"string"}},"required":["id","slug","name","personal","role","memberCount","domainJoin","createdAt"]},"Role":{"type":"string","enum":["owner","admin","member"]},"OrgSummary":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"memberCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","slug","name","memberCount"]},"Member":{"type":"object","properties":{"userId":{"type":"string"},"kind":{"type":"string","enum":["human","bot"]},"handle":{"type":"string"},"displayName":{"type":"string"},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"$ref":"#/components/schemas/Role"},"joinedAt":{"type":"string"}},"required":["userId","kind","handle","displayName","email","role","joinedAt"]},"Invite":{"type":"object","properties":{"id":{"type":"string"},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"$ref":"#/components/schemas/Role"},"token":{"type":"string"},"url":{"type":"string"},"createdAt":{"type":"string"},"expiresAt":{"type":"string"},"createdBy":{"type":"string"}},"required":["id","email","role","token","url","createdAt","expiresAt","createdBy"]},"InvitePreview":{"type":"object","properties":{"orgId":{"type":"string"},"orgName":{"type":"string"},"role":{"$ref":"#/components/schemas/Role"},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiresAt":{"type":"string"}},"required":["orgId","orgName","role","email","expiresAt"]},"Destination":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"$ref":"#/components/schemas/DestinationKind"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"builtin":{"type":"boolean"},"baseId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","kind","url","builtin","baseId"]},"DestinationKind":{"type":"string","enum":["fab","distributor","manual"]},"BotConnectRequest":{"type":"object","properties":{"name":{"type":"string"},"agentKind":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedOrgSlug":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiresAt":{"type":"string"},"status":{"type":"string","enum":["pending","approved","denied","expired"]}},"required":["name","agentKind","requestedOrgSlug","expiresAt","status"]},"CartSummary":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"name":{"type":"string"},"repos":{"type":"array","items":{"type":"string"}},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"fabDestinationId":{"type":"string"},"itemCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"updatedAt":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","orgId","name","repos","projectId","fabDestinationId","itemCount","updatedAt","createdAt"]},"Cart":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"name":{"type":"string"},"repos":{"type":"array","items":{"type":"string"}},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"fabDestinationId":{"type":"string"},"itemCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"updatedAt":{"type":"string"},"createdAt":{"type":"string"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"items":{"type":"array","items":{"$ref":"#/components/schemas/CartItem"}},"byDestination":{"type":"array","items":{"type":"object","properties":{"destinationId":{"type":"string"},"itemCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalQuantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["destinationId","itemCount","totalQuantity"]}}},"required":["id","orgId","name","repos","projectId","fabDestinationId","itemCount","updatedAt","createdAt","notes","items","byDestination"]},"CartItem":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["pcb","part","other"]},"mpn":{"type":"string"},"manufacturer":{"type":"string"},"description":{"type":"string"},"value":{"type":"string"},"footprint":{"type":"string"},"refs":{"type":"array","items":{"type":"string"}},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"destinationId":{"type":"string"},"sku":{"type":"string"},"url":{"type":"string"},"unitPrice":{"type":"number"},"currency":{"type":"string"},"status":{"type":"string","enum":["needed","ordered","received"]},"notes":{"type":"string"},"inventoryItemId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","kind","quantity","destinationId","status","createdAt","updatedAt"]},"CartItemInput":{"type":"object","properties":{"kind":{"type":"string","enum":["pcb","part","other"]},"mpn":{"type":"string","maxLength":200},"manufacturer":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":2000},"value":{"type":"string","maxLength":200},"footprint":{"type":"string","maxLength":300},"refs":{"maxItems":500,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"quantity":{"type":"integer","minimum":0,"maximum":100000000},"destinationId":{"type":"string","minLength":1,"maxLength":64},"sku":{"type":"string","maxLength":200},"url":{"type":"string","maxLength":2000},"unitPrice":{"type":"number","minimum":0,"maximum":100000000},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"status":{"type":"string","enum":["needed","ordered","received"]},"notes":{"type":"string","maxLength":4000},"inventoryItemId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["quantity"],"additionalProperties":false},"InventoryItem":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"name":{"type":"string"},"mpn":{"type":"string"},"manufacturer":{"type":"string"},"sku":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unit":{"type":"string"},"location":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"attributes":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"source":{"type":"string"},"externalId":{"type":"string"},"images":{"type":"array","items":{"$ref":"#/components/schemas/InventoryImage"}},"photoSearch":{"$ref":"#/components/schemas/PhotoSearch"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","orgId","name","quantity","unit","tags","attributes","images","photoSearch","createdBy","createdAt","updatedAt"]},"InventoryImage":{"type":"object","properties":{"id":{"type":"string"},"contentType":{"type":"string"},"bytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"url":{"type":"string"},"source":{"type":"string"},"sourceUrl":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","contentType","bytes","url","createdAt"]},"PhotoSearch":{"type":"object","properties":{"status":{"type":"string","enum":["queued","skipped"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"leaseUntil":{"anyOf":[{"type":"string"},{"type":"null"}]},"leaseOwner":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","attempts","note","leaseUntil","leaseOwner"]},"InventoryItemInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"mpn":{"type":"string","maxLength":200},"manufacturer":{"type":"string","maxLength":200},"sku":{"type":"string","maxLength":200},"category":{"type":"string","maxLength":120},"description":{"type":"string","maxLength":4000},"quantity":{"type":"integer","minimum":0,"maximum":1000000000},"unit":{"type":"string","minLength":1,"maxLength":32},"location":{"type":"string","maxLength":300},"tags":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"attributes":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":100},"additionalProperties":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"source":{"type":"string","minLength":1,"maxLength":80},"externalId":{"type":"string","minLength":1,"maxLength":200},"serverAiProcessing":{"type":"boolean"}},"required":["name"],"additionalProperties":false},"PhotoQueueItem":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"mpn":{"type":"string"},"manufacturer":{"type":"string"},"sku":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"attributes":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"tags":{"type":"array","items":{"type":"string"}},"photoSearch":{"$ref":"#/components/schemas/PhotoSearch"}},"required":["id","name","attributes","tags","photoSearch"]},"PhotoQueueCounts":{"type":"object","properties":{"queued":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"available":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"leased":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"skipped":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["queued","available","leased","skipped"]},"ClaimedPhotoQueueItem":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"mpn":{"type":"string"},"manufacturer":{"type":"string"},"sku":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"attributes":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"tags":{"type":"array","items":{"type":"string"}},"photoSearch":{"$ref":"#/components/schemas/PhotoSearch"},"leaseToken":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id","name","attributes","tags","photoSearch","leaseToken"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}},"responses":{"Error":{"description":"Error (`invalid_json`, `invalid_request`, `unauthorized`, `forbidden`, `not_found`, `conflict`, …)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`fpk_…` personal API token or `fpd_…` device token"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"fp_session"}}}}