{ "openapi": "3.0.3", "info": { "title": "Shepherd API", "version": "1.1.0", "description": "Programmatic access to Shepherd's ledger: connect wallets, classify transactions, and pull financial statements. Start with an instant sandbox key (POST /sandbox/signup). Live keys are issued to partners." }, "servers": [ { "url": "https://app.getshepherd.co/api/v1" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key beginning shep_live_" } } }, "paths": { "/wallets": { "get": { "tags": [ "Wallets" ], "summary": "List connected wallets.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "end_user_id", "in": "query", "required": false, "description": "Only wallets tagged with this end user.", "schema": { "type": "string" } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Wallets" ], "summary": "Connect a wallet, pull its history, and auto-classify what it finds. Returns 201.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "201": { "description": "Created" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address." }, "chain": { "type": "string", "description": "One of base, ethereum, polygon, arbitrum, tempo, solana." }, "end_user_id": { "type": "string", "description": "Your own identifier for the customer who owns this wallet. Created on first use." }, "end_user_name": { "type": "string", "description": "Display name for a new end user." }, "name": { "type": "string", "description": "Label for the wallet. Defaults to the address." }, "lookback_blocks": { "type": "integer", "description": "How far back to scan on EVM chains. Default 2000." } }, "required": [ "address", "chain" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/wallets/{wallet_id}/scan": { "post": { "tags": [ "Wallets" ], "summary": "Rescan a wallet for new activity. Add async: true to return 202 with a job_id right away instead of waiting.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." }, "202": { "description": "Accepted as a background job" } }, "parameters": [ { "name": "wallet_id", "in": "path", "required": true, "description": "Wallet id from GET /wallets.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "async": { "type": "boolean", "description": "Run in the background and return a job (GET /jobs/{job_id})." } } } } } } } }, "/accounts": { "get": { "tags": [ "Accounts" ], "summary": "List accounts you push transactions to (bank accounts, cards, and custodial stablecoin accounts).", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." }, "201": { "description": "Created" } }, "parameters": [ { "name": "end_user_id", "in": "query", "required": false, "description": "Only accounts for this end user.", "schema": { "type": "string" } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Accounts" ], "summary": "Create an account, or return the existing one with the same external_id. Returns 201 when created, 200 otherwise.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." }, "201": { "description": "Created" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_id": { "type": "string", "description": "Your id for this account." }, "name": { "type": "string", "description": "Display name." }, "type": { "type": "string", "description": "bank, credit_card, stablecoin, or ledger. Default bank." }, "currency": { "type": "string", "description": "USD, EUR, USDC and so on. Default USD (USDC for stablecoin and ledger)." }, "end_user_id": { "type": "string", "description": "Your id for the customer who owns it. Created on first use." }, "end_user_name": { "type": "string", "description": "Display name for a new end user." }, "entity_id": { "type": "integer", "description": "Book this account under an entity." } }, "required": [ "external_id" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/accounts/{account_id}": { "get": { "tags": [ "Accounts" ], "summary": "Fetch one account.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "Account id.", "schema": { "type": "integer" } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/accounts/{account_id}/transactions": { "get": { "tags": [ "Accounts" ], "summary": "Transactions for one account. Same filters and pagination as GET /transactions.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "Account id.", "schema": { "type": "integer" } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Accounts" ], "summary": "Push up to 1000 transactions. Each is keyed by your external_id, so sending one again changes nothing, and sending it with a corrected amount or date updates it. Returns 200, or 207 when some items were rejected (listed with their index and reason). By default new transactions are then classified in the background.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." }, "207": { "description": "Some items were rejected; see rejected[]" } }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "Account id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactions": { "type": "array", "description": "Items: external_id (required), date YYYY-MM-DD (required), amount (required), direction inflow or outflow (a negative amount means outflow if omitted), counterparty, currency or asset, category, merchant_id, pending." }, "classify": { "type": "boolean", "description": "Classify new transactions in the background. Default true." } }, "required": [ "transactions" ] } } } } } }, "/accounts/{account_id}/classify": { "post": { "tags": [ "Accounts" ], "summary": "Classify the account's unclassified transactions in the background. Returns 202 with a job_id.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." }, "202": { "description": "Accepted as a background job" } }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "Account id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/jobs": { "get": { "tags": [ "Jobs" ], "summary": "Your 50 most recent background jobs.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/jobs/{job_id}": { "get": { "tags": [ "Jobs" ], "summary": "Status of a background job: queued, running, succeeded or failed, with its result or error.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Job id from a 202 response.", "schema": { "type": "string" } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/transactions": { "get": { "tags": [ "Transactions" ], "summary": "List transactions with their classification, newest first. Paginated: pass next_cursor back as cursor until has_more is false.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "wallet_id", "in": "query", "required": false, "description": "Filter to one wallet.", "schema": { "type": "string" } }, { "name": "end_user_id", "in": "query", "required": false, "description": "Filter to one end user.", "schema": { "type": "string" } }, { "name": "gl_code", "in": "query", "required": false, "description": "Filter to one chart-of-accounts code.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "unclassified, classified, or pending_approval.", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "description": "YYYY-MM-DD, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "description": "YYYY-MM-DD, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601 timestamp. Returns only transactions created or changed after it, oldest change first, so you can keep a copy in sync.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 1000. Default 500.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor from the previous page.", "schema": { "type": "string" } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/transactions/{transaction_id}": { "get": { "tags": [ "Transactions" ], "summary": "Fetch one transaction.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "Transaction id.", "schema": { "type": "integer" } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/transactions/{transaction_id}/classify": { "post": { "tags": [ "Transactions" ], "summary": "Set or change a transaction's GL code. Changes to an already-classified transaction are recorded as reclassifications.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "Transaction id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "gl_code": { "type": "string", "description": "A code from the chart of accounts, or 'Unclassified'." }, "counterparty": { "type": "string", "description": "Counterparty name to store with the transaction." }, "reason": { "type": "string", "description": "Why it was reclassified. Kept in the audit trail." } }, "required": [ "gl_code" ] } } } } } }, "/transactions/link-suggestions": { "get": { "tags": [ "Transactions" ], "summary": "Suggested pairs of transactions (for example a bank leg and a wallet leg of one conversion) for you to confirm.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/transactions/link": { "post": { "tags": [ "Transactions" ], "summary": "Link two transactions as the two legs of one event.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tx_id_a": { "type": "integer", "description": "First transaction." }, "tx_id_b": { "type": "integer", "description": "Second transaction." }, "note": { "type": "string", "description": "Optional note." } }, "required": [ "tx_id_a", "tx_id_b" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/transactions/links": { "get": { "tags": [ "Transactions" ], "summary": "List confirmed links.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/transactions/links/{link_id}/unlink": { "post": { "tags": [ "Transactions" ], "summary": "Remove a link.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "link_id", "in": "path", "required": true, "description": "Link id from GET /transactions/links.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/transactions/link-suggestions/dismiss": { "post": { "tags": [ "Transactions" ], "summary": "Dismiss a suggested pair so it stops appearing.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tx_id_a": { "type": "integer", "description": "First transaction." }, "tx_id_b": { "type": "integer", "description": "Second transaction." } }, "required": [ "tx_id_a", "tx_id_b" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/financial-statements": { "get": { "tags": [ "Financial statements" ], "summary": "Income statement totals: revenue and expense by account, fair value and FX gains, net income, plus counts of unclassified and unpriced activity.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "start_date", "in": "query", "required": false, "description": "YYYY-MM-DD, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "required": false, "description": "YYYY-MM-DD, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "entity_id", "in": "query", "required": false, "description": "Limit to one entity.", "schema": { "type": "integer" } }, { "name": "wallet_id", "in": "query", "required": false, "description": "Limit to one wallet.", "schema": { "type": "string" } }, { "name": "end_user_id", "in": "query", "required": false, "description": "Limit to one end user.", "schema": { "type": "string" } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/financial-statements/consolidated": { "get": { "tags": [ "Financial statements" ], "summary": "Income statement consolidated across entities.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "start_date", "in": "query", "required": false, "description": "YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "required": false, "description": "YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/balance-sheet": { "get": { "tags": [ "Financial statements" ], "summary": "Balance sheet for one entity, or the whole organization if entity_id is omitted.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "entity_id", "in": "query", "required": false, "description": "Limit to one entity.", "schema": { "type": "integer" } }, { "name": "as_of_date", "in": "query", "required": false, "description": "YYYY-MM-DD. Defaults to today.", "schema": { "type": "string", "format": "date" } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/balance-sheet/consolidated": { "get": { "tags": [ "Financial statements" ], "summary": "Consolidated balance sheet, including the cumulative translation adjustment for entities with different functional currencies.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "as_of_date", "in": "query", "required": false, "description": "YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "period_start_date", "in": "query", "required": false, "description": "YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/entities": { "get": { "tags": [ "Entities" ], "summary": "List entities (separate sets of books).", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Entities" ], "summary": "Create an entity.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Entity name." }, "legal_name": { "type": "string", "description": "Legal name." }, "entity_type": { "type": "string", "description": "Entity type." }, "functional_currency": { "type": "string", "description": "ISO currency code." } }, "required": [ "name" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/entities/{entity_id}/update": { "post": { "tags": [ "Entities" ], "summary": "Update an entity.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "entity_id", "in": "path", "required": true, "description": "Entity id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Entity name." }, "legal_name": { "type": "string", "description": "Legal name." }, "entity_type": { "type": "string", "description": "Entity type." }, "functional_currency": { "type": "string", "description": "ISO currency code." }, "clear_functional_currency": { "type": "boolean", "description": "Set true to remove the functional currency." } }, "required": [ "name" ] } } } } } }, "/entities/{entity_id}/delete": { "post": { "tags": [ "Entities" ], "summary": "Delete an entity.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "entity_id", "in": "path", "required": true, "description": "Entity id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/opening-balances": { "get": { "tags": [ "Opening balances" ], "summary": "List opening balances.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Opening balances" ], "summary": "Record a balance carried in from before Shepherd.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_name": { "type": "string", "description": "Account the balance belongs to." }, "account_type": { "type": "string", "description": "asset, liability, equity, revenue, or expense." }, "amount": { "type": "number", "description": "Balance." }, "as_of_date": { "type": "string", "format": "date", "description": "YYYY-MM-DD." }, "currency": { "type": "string", "description": "ISO code. Default USD." }, "gl_code": { "type": "string", "description": "Chart-of-accounts code." } }, "required": [ "account_name", "account_type", "amount", "as_of_date" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/opening-balances/{balance_id}/delete": { "post": { "tags": [ "Opening balances" ], "summary": "Delete an opening balance.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "balance_id", "in": "path", "required": true, "description": "Opening balance id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/accruals": { "get": { "tags": [ "Accruals" ], "summary": "List AR invoices and AP bills, with any possible duplicates flagged.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Accruals" ], "summary": "Record an AR invoice or AP bill, optionally recognized over several months.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entry_type": { "type": "string", "description": "ar_invoice or ap_bill." }, "amount": { "type": "number", "description": "Amount." }, "issue_date": { "type": "string", "format": "date", "description": "YYYY-MM-DD." }, "gl_code": { "type": "string", "description": "Chart-of-accounts code." }, "counterparty": { "type": "string", "description": "Customer or vendor." }, "description": { "type": "string", "description": "Free text." }, "due_date": { "type": "string", "format": "date", "description": "YYYY-MM-DD." }, "recognition_start_date": { "type": "string", "format": "date", "description": "Start of recognition." }, "recognition_months": { "type": "integer", "description": "Months to recognize over." }, "external_source": { "type": "string", "description": "Name of the system the entry came from." }, "external_id": { "type": "string", "description": "Its id in that system." } }, "required": [ "entry_type", "amount", "issue_date" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/accruals/{accrual_id}/match": { "post": { "tags": [ "Accruals" ], "summary": "Match an invoice or bill to the on-chain payment that settled it.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "accrual_id", "in": "path", "required": true, "description": "Accrual id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tx_hash": { "type": "string", "description": "Settling transaction hash." }, "wallet_address": { "type": "string", "description": "Wallet that sent or received it." }, "chain": { "type": "string", "description": "Chain of the transaction." }, "matched_date": { "type": "string", "format": "date", "description": "YYYY-MM-DD." } }, "required": [ "tx_hash", "wallet_address", "chain", "matched_date" ] } } } } } }, "/accruals/{accrual_id}/delete": { "post": { "tags": [ "Accruals" ], "summary": "Delete an accrual.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "accrual_id", "in": "path", "required": true, "description": "Accrual id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/classification-rules": { "get": { "tags": [ "Classification rules" ], "summary": "List rules that classify matching activity automatically.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Classification rules" ], "summary": "Create a rule. A transaction matching every field you set gets the GL code.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "gl_code": { "type": "string", "description": "Code to apply." }, "direction": { "type": "string", "description": "Direction of the transaction." }, "chain": { "type": "string", "description": "Chain." }, "counterparty": { "type": "string", "description": "Counterparty." }, "amount_min": { "type": "number", "description": "Lower bound." }, "amount_max": { "type": "number", "description": "Upper bound." }, "entity_id": { "type": "integer", "description": "Limit to an entity." } }, "required": [ "gl_code" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/classification-rules/{rule_id}/delete": { "post": { "tags": [ "Classification rules" ], "summary": "Delete a rule.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "rule_id", "in": "path", "required": true, "description": "Rule id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/reconciliation": { "get": { "tags": [ "Reconciliation" ], "summary": "Compare each wallet's balance computed from transactions against its live on-chain balance.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/reconciliation/baseline": { "post": { "tags": [ "Reconciliation" ], "summary": "Set a baseline balance for a wallet, so later checks measure activity from that point.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet_id": { "type": "string", "description": "Wallet id." }, "balance": { "type": "number", "description": "Balance at baseline." } }, "required": [ "wallet_id", "balance" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/chart-of-accounts": { "get": { "tags": [ "Chart of accounts" ], "summary": "The chart of accounts.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Chart of accounts" ], "summary": "Add accounts, or with replace: true (admin key) replace the whole chart. Existing codes are never overwritten by an add.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "description": "Items: code and name (required), account_type (asset, liability, equity, revenue, expense, transfer), description, parent_code." }, "replace": { "type": "boolean", "description": "Replace the whole chart. Needs an admin key." } }, "required": [ "accounts" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/periods": { "get": { "tags": [ "Periods" ], "summary": "The closed-through date, close history, and late-arriving activity.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/periods/close": { "post": { "tags": [ "Periods" ], "summary": "Close the books through a month-end. Activity dated on or before it can no longer change; late arrivals are flagged instead. Needs an admin key.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "through": { "type": "string", "format": "date", "description": "A month-end, YYYY-MM-DD, not in the future." }, "note": { "type": "string", "description": "Optional note kept in the audit trail." } }, "required": [ "through" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/periods/reopen": { "post": { "tags": [ "Periods" ], "summary": "Reopen to an earlier month-end, or null to reopen everything. A note is required. Needs an admin key.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "format": "date", "description": "Month-end to reopen to, or null." }, "note": { "type": "string", "description": "Why. Kept in the audit trail." } }, "required": [ "note" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/audit-log": { "get": { "tags": [ "Audit log" ], "summary": "What changed and who changed it, newest first.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "1 to 500. Default 100.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page.", "schema": { "type": "string" } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/api-keys": { "get": { "tags": [ "API keys" ], "summary": "List your keys: label, prefix, scope, last use, expiry. Never the secret. Needs an admin key.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." }, "201": { "description": "Created" } }, "parameters": [ { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] }, "post": { "tags": [ "API keys" ], "summary": "Create a key. The secret is shown once. Returns 201. Needs an admin key.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." }, "201": { "description": "Created" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "A name for the key." }, "scope": { "type": "string", "description": "read, write or admin. Default write." }, "expires_in_days": { "type": "integer", "description": "The key stops working after this many days." }, "rate_limit_per_min": { "type": "integer", "description": "Lower or raise this key's request limit." } } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/api-keys/{key_id}/rotate": { "post": { "tags": [ "API keys" ], "summary": "Issue a replacement with the same scope and limits. The old key keeps working for grace_hours (default 24). Returns 201.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." }, "201": { "description": "Created" } }, "parameters": [ { "name": "key_id", "in": "path", "required": true, "description": "Key id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "grace_hours": { "type": "integer", "description": "0 to 720. 0 revokes the old key immediately." } } } } } } } }, "/api-keys/{key_id}/revoke": { "post": { "tags": [ "API keys" ], "summary": "Revoke a key immediately.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "key_id", "in": "path", "required": true, "description": "Key id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/workspaces": { "get": { "tags": [ "Workspaces" ], "summary": "List your customers' workspaces. Platform accounts only.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." }, "201": { "description": "Created" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "1 to 500. Default 100.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page.", "schema": { "type": "string" } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Workspaces" ], "summary": "Create a workspace for one of your customers, or return the existing one with the same external_id. Returns 201 when created.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." }, "201": { "description": "Created" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_id": { "type": "string", "description": "Your id for the customer." }, "name": { "type": "string", "description": "Display name." }, "contact_email": { "type": "string", "description": "Optional." } }, "required": [ "external_id", "name" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/workspaces/{workspace_id}": { "get": { "tags": [ "Workspaces" ], "summary": "Fetch a workspace by its external_id or its Shepherd id.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "description": "external_id or id.", "schema": { "type": "string" } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/workspaces/{workspace_id}/update": { "post": { "tags": [ "Workspaces" ], "summary": "Rename a workspace.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "description": "external_id or id.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name." } }, "required": [ "name" ] } } } } } }, "/workspaces/{workspace_id}/delete": { "post": { "tags": [ "Workspaces" ], "summary": "Permanently delete a workspace and all of its data.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "description": "external_id or id.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm": { "type": "string", "description": "Must equal the workspace's external_id." } }, "required": [ "confirm" ] } } } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List your webhook endpoints and the event types you can subscribe to.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Register an endpoint. The response includes its signing secret, shown once. The URL must be https and publicly reachable. Returns 201.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "201": { "description": "Created" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Where Shepherd sends events." }, "events": { "type": "array", "description": "Event types to receive, or [\"*\"] for all. Default all." }, "description": { "type": "string", "description": "Label for the endpoint." } }, "required": [ "url" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/webhooks/{webhook_id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Queue a ping event to one endpoint.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "description": "Webhook id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/webhooks/{webhook_id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "The 50 most recent deliveries to an endpoint, with status, attempts and last error.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid parameter" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "description": "Webhook id.", "schema": { "type": "integer" } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/webhooks/{webhook_id}/delete": { "post": { "tags": [ "Webhooks" ], "summary": "Delete an endpoint.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "description": "Webhook id.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } }, "/sandbox/signup": { "post": { "tags": [ "Sandbox" ], "summary": "Create a sandbox and get a shep_test_ key instantly. No authentication. Returns 201.", "security": [], "responses": { "200": { "description": "Success" }, "201": { "description": "Created" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Optional. Where to reach you about the integration." }, "name": { "type": "string", "description": "Optional label." } } } } } } } }, "/sandbox/reset": { "post": { "tags": [ "Sandbox" ], "summary": "Reset the sandbox to its seed data. Sandbox keys only.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Invalid or missing API key" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limit exceeded. See Retry-After." } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry the same request safely. Same key and body returns the first response for 24 hours.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Shepherd-Workspace", "in": "header", "required": false, "description": "Platform accounts: act inside one customer's workspace (its external_id).", "schema": { "type": "string" } } ] } } } }