diff --git a/.agents/skills/add-block/SKILL.md b/.agents/skills/add-block/SKILL.md index 091a8307c31..fb60d3c0649 100644 --- a/.agents/skills/add-block/SKILL.md +++ b/.agents/skills/add-block/SKILL.md @@ -172,8 +172,8 @@ Optional companions: `credentialLabels` (override the picker's section/connect-r ### OAuth deployment availability (required for integration blocks) A visible tools-category block with OAuth is deployment-gated. Its `oauth-input.serviceId` is -projected into `apps/sim/lib/integrations/integrations.json`, then resolved through -`resolveOAuthClientCapabilityId()` in `apps/sim/lib/core/config/env-capabilities.ts`. +projected into `packages/deployment-config/src/integrations.json`, then resolved through +`resolveOAuthClientCapabilityId()` in `packages/deployment-config/src/env-capabilities.ts`. When adding or changing an OAuth integration block: @@ -184,13 +184,14 @@ When adding or changing an OAuth integration block: 3. For a new capability, add its required client fields to `OAUTH_CLIENT_CAPABILITIES` and ensure every referenced field exists in the env schema in `apps/sim/lib/core/config/env.ts`. Then add the matching `text` or `secret` input modes to `OAUTH_CLIENT_SETUP_FIELDS` in - `scripts/setup/capability-config.ts`. The CLI catalog is exhaustively typed and checked against - the runtime field list; do not infer secrecy from the field name. -4. If the canonical OAuth service declares `serviceAccountProviderId`, keep - `SERVICE_ACCOUNT_METADATA_BY_OAUTH_SERVICE_ID` in - `apps/sim/lib/integrations/service-account-metadata.ts` aligned. Set - `deploymentRequirement` only when the service-account path is preview-gated or depends on the - OAuth client fields; otherwise omit it. + `packages/sim-setup/src/capability-config.ts`. The CLI catalog is exhaustively typed and checked + against the runtime field list; do not infer secrecy from the field name. +4. If the canonical OAuth service declares `serviceAccountProviderId`, run + `bun run deployment-config:generate`; this regenerates the provider-ID facts in + `packages/deployment-config/src/service-account-providers.generated.ts`. Never hand-edit that + generated map. Add `deploymentRequirement` policy in + `packages/deployment-config/src/service-account-metadata.ts` only when the service-account path + is preview-gated or depends on the OAuth client fields; otherwise omit it. Missing capability metadata is a runtime configuration error, not a reason to make the integration silently available. @@ -992,16 +993,21 @@ After adding or changing one, run: ```bash bun run scripts/generate-docs.ts +bun run deployment-config:generate bun run integration-catalog:check +bun run deployment-config:check bun run docs:check ``` The catalog check independently derives deployment metadata from the executable block registry and -compares it with the committed `apps/sim/lib/integrations/integrations.json`. `docs:check` re-renders -every generated docs artifact in memory and fails on any committed file that differs — it runs in CI -via `check:audits`, so commit the full generator output. If the generator also trues up pages an -earlier PR left stale, commit that catch-up too; reverting it as "unrelated drift" makes `docs:check` -fail. +compares it with the committed `packages/deployment-config/src/integrations.json`. The deployment +config check verifies the generated service-account facts against the canonical OAuth registry and +catalog. `docs:check` re-renders every generated docs artifact in memory and fails on any committed +file that differs — it runs in CI via `check:audits`, so commit the full generator output. If the +generator also trues up pages an earlier PR left stale, commit that catch-up too; reverting it as +"unrelated drift" makes `docs:check` fail. Review the generated diff and keep only intentional +changes. + ## Checklist Before Finishing - [ ] `integrationType` is set to the correct `IntegrationType` enum value @@ -1046,3 +1052,34 @@ After creating the block, you MUST validate it against every tool it references: 4. **Verify conditions** — each subBlock should only show for the operations that actually use it 5. **Verify `{Service}BlockMeta` is exported** with at least 7 templates, each having `icon`, `title`, `prompt`, `modules`, `category`, and `tags` 6. **If any tool outputs are still unknown**, explicitly tell the user instead of guessing block outputs + +## Option Lists: `selectorKey` or `options`, never a per-block fetcher + +A sub-block gets its choices from exactly one of two places. There is no third. + +**`selectorKey` — every remote list.** Register the list in `hooks/selectors/providers//selectors.ts`, add its key to `SelectorKey`, and point the sub-block at it. A selector is parameterized by an explicit `SelectorContext`, so the same definition serves the canvas, the workspace-fork sync modal, and anything added later. + +```ts +{ id: 'triggerCredentials', type: 'oauth-input', canonicalParamId: 'oauthCredential', mode: 'trigger' }, +{ id: 'labelIds', type: 'dropdown', multiSelect: true, + selectorKey: 'gmail.labels', dependsOn: ['triggerCredentials'], mode: 'trigger' }, +{ id: 'manualLabelIds', type: 'short-input', mode: 'trigger-advanced' }, +``` + +`canonicalParamId: 'oauthCredential'` on the credential sub-block is the line people forget. `buildSelectorContextFromBlock` keys the context on a sub-block's CANONICAL id, so without it `context.oauthCredential` is never set and the picker looks unfixable without reading the store. (A credential field is also recognised by its `oauth-input` TYPE as a fallback, so a block whose shipped param is already named something else does not have to rename it.) + +**`options` — everything else.** A static array, or a pure function of the block's own values for a list that narrows to a sibling's selection. No I/O. + +```ts +options: (params) => { + const model = params?.values.model + return typeof model === 'string' ? effortsFor(model) : DEFAULT_EFFORTS +} +``` + +**Never fetch inside `options`, and never reach into the stores from a block definition.** A fetcher that resolves its credential with `readSubBlockValue(blockId, ...)` only works on the canvas — every surface that is not the editor gets an empty list. `fetchOptions`/`fetchOptionById` were removed for exactly this reason. + +Two rules the checks enforce: + +- **A secret never enters a selector's `getQueryKey`.** A query key identifies a resource; a credential authorizes access to it. A credential *id* is fine; a typed password is not (see `imap.mailboxes`). +- **A sub-block that `dependsOn` a credential / knowledge-base / table selector must be reconfigurable at fork-sync time** — a `selectorKey`, a canonical pair whose basic member is a selector, or a `short-input`/`long-input`. `bun run check:fork-dependent-coverage` fails otherwise, because a fork sync clears those fields on every push and an unofferable one can never be set anywhere that sticks. diff --git a/.agents/skills/add-integration/SKILL.md b/.agents/skills/add-integration/SKILL.md index 22ed2ef4195..3f3bbaccf9a 100644 --- a/.agents/skills/add-integration/SKILL.md +++ b/.agents/skills/add-integration/SKILL.md @@ -538,16 +538,18 @@ the OAuth service configuration, deployment availability, and the setup CLI. 1. Ensure the block has exactly one distinct OAuth `serviceId` and that it matches the canonical service entry in `apps/sim/lib/oauth/oauth.ts`. 2. Confirm `resolveOAuthClientCapabilityId(serviceId)` resolves to the intended provider entry in - `OAUTH_CLIENT_CAPABILITIES` in `apps/sim/lib/core/config/env-capabilities.ts`. Google and + `OAUTH_CLIENT_CAPABILITIES` in `packages/deployment-config/src/env-capabilities.ts`. Google and Microsoft service IDs deliberately share provider-level capabilities. 3. For a new OAuth provider, add the required client fields to `OAUTH_CLIENT_CAPABILITIES`, add every referenced field to the env schema in `apps/sim/lib/core/config/env.ts`, and add the matching `text` or `secret` entries to `OAUTH_CLIENT_SETUP_FIELDS` in - `scripts/setup/capability-config.ts`. Do not create integration-specific setup logic or infer - secret fields from naming; the CLI mapping is exhaustively checked against the runtime fields. -4. If the canonical OAuth service has `serviceAccountProviderId`, add the matching projection to - `SERVICE_ACCOUNT_METADATA_BY_OAUTH_SERVICE_ID` in - `apps/sim/lib/integrations/service-account-metadata.ts`. Use: + `packages/sim-setup/src/capability-config.ts`. Do not create integration-specific setup logic or + infer secret fields from naming; the CLI mapping is exhaustively checked against the runtime + fields. +4. If the canonical OAuth service has `serviceAccountProviderId`, run + `bun run deployment-config:generate` to refresh + `packages/deployment-config/src/service-account-providers.generated.ts`; never hand-edit the + generated provider-ID map. In `packages/deployment-config/src/service-account-metadata.ts`, use: - no `deploymentRequirement` when the service-account path works independently of OAuth client fields; - `'oauth-client'` when it requires the same deployment OAuth client fields; - `'preview-gated'` when availability is controlled by the service-account preview block. @@ -560,15 +562,18 @@ a resolvable capability must fail validation. Run the documentation generator: ```bash bun run scripts/generate-docs.ts +bun run deployment-config:generate bun run integration-catalog:check +bun run deployment-config:check bun run docs:check ``` This creates `apps/docs/content/docs/en/integrations/{service}.mdx` — one page per service carrying the block's Actions and, if it has one, its Triggers section. Never hand-edit generated pages; the only editable region is the `{/* MANUAL-CONTENT */}` block (see `scripts/README.md`). -The same generator refreshes `apps/sim/lib/integrations/integrations.json`. The catalog check then -derives the deployment-relevant fields from the executable block registry and compares them with the -committed projection. Review the generated diff and keep only intentional changes. +The docs generator refreshes `packages/deployment-config/src/integrations.json`, and the deployment +config generator projects service-account provider IDs from that catalog plus the canonical OAuth +registry. The checks compare both committed projections with their sources. Review the generated +diff and keep only intentional changes. ## V2 Integration Pattern @@ -647,14 +652,16 @@ If creating V2 versions (API-aligned outputs): - [ ] Created `index.ts` barrel export - [ ] Registered all triggers in `triggers/registry.ts` -### Docs +### Docs and deployment metadata - [ ] Ran `bun run scripts/generate-docs.ts` +- [ ] Ran `bun run deployment-config:generate` for OAuth or service-account changes - [ ] Verified docs file created -- [ ] Reviewed and committed the generated `apps/sim/lib/integrations/integrations.json` change +- [ ] Reviewed and committed the generated `packages/deployment-config/src/integrations.json` change - [ ] `bun run integration-catalog:check` passes - [ ] `bun run docs:check` passes — CI fails on stale generated docs, so commit the full generator output, including catch-up regeneration for pages another PR left stale (never revert it as "unrelated drift") +- [ ] `bun run deployment-config:check` passes ### Final Validation (Required) - [ ] Read every tool file and cross-referenced inputs/outputs against the API docs @@ -1002,4 +1009,4 @@ requiredScopes: getScopesForService('{service}'), 11. **Never hardcode scopes** - Use `getScopesForService()` in blocks and `getCanonicalScopesForProvider()` in auth.ts 12. **Always add scope descriptions** - New scopes must have entries in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts` 13. **OAuth service IDs need deployment capabilities** - Every visible OAuth integration must resolve through `OAUTH_CLIENT_CAPABILITIES`; shared Google/Microsoft aliases map to their provider capability -14. **Keep runtime and presentation separate** - Runtime OAuth fields live in `env-capabilities.ts`; CLI input modes live in the exhaustively checked `scripts/setup/capability-config.ts` mapping +14. **Keep runtime and presentation separate** - Runtime OAuth fields live in `packages/deployment-config/src/env-capabilities.ts`; CLI input modes live in the exhaustively checked `packages/sim-setup/src/capability-config.ts` mapping diff --git a/.agents/skills/add-trigger/SKILL.md b/.agents/skills/add-trigger/SKILL.md index 3175d46e1c8..bfec917d60b 100644 --- a/.agents/skills/add-trigger/SKILL.md +++ b/.agents/skills/add-trigger/SKILL.md @@ -472,6 +472,37 @@ Add to `helm/sim/values.yaml` under the existing polling cron jobs: - Cursor-based (changes API): `apps/sim/lib/webhooks/polling/google-drive.ts` - Timestamp-based: `apps/sim/lib/webhooks/polling/google-calendar.ts` +## Option Lists: `selectorKey` or `options`, never a per-block fetcher + +A sub-block gets its choices from exactly one of two places. There is no third. + +**`selectorKey` — every remote list.** Register the list in `hooks/selectors/providers//selectors.ts`, add its key to `SelectorKey`, and point the sub-block at it. A selector is parameterized by an explicit `SelectorContext`, so the same definition serves the canvas, the workspace-fork sync modal, and anything added later. + +```ts +{ id: 'triggerCredentials', type: 'oauth-input', canonicalParamId: 'oauthCredential', mode: 'trigger' }, +{ id: 'labelIds', type: 'dropdown', multiSelect: true, + selectorKey: 'gmail.labels', dependsOn: ['triggerCredentials'], mode: 'trigger' }, +{ id: 'manualLabelIds', type: 'short-input', mode: 'trigger-advanced' }, +``` + +`canonicalParamId: 'oauthCredential'` on the credential sub-block is the line people forget. `buildSelectorContextFromBlock` keys the context on a sub-block's CANONICAL id, so without it `context.oauthCredential` is never set and the picker looks unfixable without reading the store. (A credential field is also recognised by its `oauth-input` TYPE as a fallback, so a block whose shipped param is already named something else does not have to rename it.) + +**`options` — everything else.** A static array, or a pure function of the block's own values for a list that narrows to a sibling's selection. No I/O. + +```ts +options: (params) => { + const model = params?.values.model + return typeof model === 'string' ? effortsFor(model) : DEFAULT_EFFORTS +} +``` + +**Never fetch inside `options`, and never reach into the stores from a block definition.** A fetcher that resolves its credential with `readSubBlockValue(blockId, ...)` only works on the canvas — every surface that is not the editor gets an empty list. `fetchOptions`/`fetchOptionById` were removed for exactly this reason. + +Two rules the checks enforce: + +- **A secret never enters a selector's `getQueryKey`.** A query key identifies a resource; a credential authorizes access to it. A credential *id* is fine; a typed password is not (see `imap.mailboxes`). +- **A sub-block that `dependsOn` a credential / knowledge-base / table selector must be reconfigurable at fork-sync time** — a `selectorKey`, a canonical pair whose basic member is a selector, or a `short-input`/`long-input`. `bun run check:fork-dependent-coverage` fails otherwise, because a fork sync clears those fields on every push and an unofferable one can never be set anywhere that sticks. + ## Checklist ### Trigger Definition diff --git a/.agents/skills/validate-integration/SKILL.md b/.agents/skills/validate-integration/SKILL.md index 68ed9ee7620..abf1740647d 100644 --- a/.agents/skills/validate-integration/SKILL.md +++ b/.agents/skills/validate-integration/SKILL.md @@ -29,12 +29,13 @@ apps/sim/blocks/registry-maps.ts # Block + meta registry entry (BLOCK_REGISTR apps/sim/components/icons.tsx # Icon definition apps/sim/lib/auth/auth.ts # OAuth config — should use getCanonicalScopesForProvider() apps/sim/lib/oauth/oauth.ts # OAuth provider config — single source of truth for scopes -apps/sim/lib/oauth/utils.ts # Scope utilities, SCOPE_DESCRIPTIONS for modal UI -apps/sim/lib/core/config/env-capabilities.ts # OAuth client runtime capability source of truth +apps/sim/lib/oauth/utils.ts # Scope utilities, SCOPE_DESCRIPTIONS for modal UI +packages/deployment-config/src/env-capabilities.ts # OAuth client runtime capability source of truth apps/sim/lib/core/config/env.ts # Runtime env schema for capability fields -scripts/setup/capability-config.ts # Exhaustive CLI input-mode mapping for OAuth fields -apps/sim/lib/integrations/integrations.json # Generated client-safe integration catalog -apps/sim/lib/integrations/service-account-metadata.ts # Lightweight service-account projection +packages/sim-setup/src/capability-config.ts # Exhaustive CLI input-mode mapping for OAuth fields +packages/deployment-config/src/integrations.json # Generated client-safe integration catalog +packages/deployment-config/src/service-account-providers.generated.ts # Generated provider-ID facts +packages/deployment-config/src/service-account-metadata.ts # Handwritten deployment policy ``` ## Step 2: Pull API Documentation @@ -291,7 +292,7 @@ Scopes are centralized — the single source of truth is `OAUTH_PROVIDERS` in `l ## Step 6: Validate Deployment Availability (if OAuth service) The deployment UI and setup CLI do not infer OAuth client fields from scopes. They resolve the -block's generated `oauthServiceId` through the application-owned capability catalog. +block's generated `oauthServiceId` through the shared deployment capability catalog. - [ ] The visible integration block has exactly one distinct `oauth-input.serviceId` - [ ] `resolveOAuthClientCapabilityId(serviceId)` returns the intended provider capability @@ -299,9 +300,9 @@ block's generated `oauthServiceId` through the application-owned capability cata - [ ] Every field listed by that capability exists in `apps/sim/lib/core/config/env.ts` - [ ] Every capability field has the correct `text` or `secret` entry in `OAUTH_CLIENT_SETUP_FIELDS`; no CLI naming heuristic is required - [ ] Shared Google/Microsoft service IDs resolve to their provider capability rather than duplicate entries -- [ ] `bun run setup integration ` is the command emitted by availability; the CLI has only the exhaustive input-mode projection, not a second runtime provider definition +- [ ] `npx sim-setup add integration ` is the command emitted by availability; the CLI has only the exhaustive input-mode projection, not a second runtime provider definition - [ ] If the canonical OAuth service declares `serviceAccountProviderId`, - `SERVICE_ACCOUNT_METADATA_BY_OAUTH_SERVICE_ID[serviceId]` has the same provider ID + the generated `SERVICE_ACCOUNT_PROVIDER_BY_OAUTH_SERVICE_ID[serviceId]` has the same provider ID - [ ] The service-account `deploymentRequirement` matches how that credential actually works: omitted for an independent path, `'oauth-client'` when it needs the OAuth client fields, or `'preview-gated'` when controlled by a preview block @@ -386,13 +387,16 @@ Several files are generated from tool and block definitions. Editing a tool or b ```bash bun run tool-metadata:generate # repo root — apps/sim/tools/generated/* -bun run scripts/generate-docs.ts # docs .mdx + lib/integrations/integrations.json + docs icons +bun run scripts/generate-docs.ts # docs .mdx + deployment-config/integrations.json + docs icons +bun run deployment-config:generate # canonical OAuth registry + catalog → provider-ID facts bun run integration-catalog:check # registry ↔ committed deployment metadata drift bun run docs:check # committed docs ↔ what the generator renders today +bun run deployment-config:check # OAuth registry/catalog ↔ provider-ID fact drift ``` - **`tool-metadata:generate`** — required whenever a tool's `outputs`, `params`, or descriptions change. CI enforces this with `bun run tool-metadata:check`, which fails with *"Generated tool metadata is stale"*. This is the easiest gate to miss, because nothing in the tool file hints that a generated artifact mirrors it. -- **`generate-docs`** — required whenever block metadata changes (`bgColor`, `name`, `description`, operations, outputs). Regenerates the integration `.mdx`, `integrations.json`, and the docs copy of `components/icons.tsx`. +- **`generate-docs`** — required whenever block metadata changes (`bgColor`, `name`, `description`, operations, outputs). Regenerates the integration `.mdx`, `packages/deployment-config/src/integrations.json`, and the docs copy of `components/icons.tsx`. +- **`deployment-config:generate`** — required for OAuth or service-account changes. Regenerates provider-ID facts from the canonical OAuth registry and integration catalog; special deployment requirements remain handwritten policy. - **`integration-catalog:check`** — loads the executable block registry, derives visible integration deployment fields, and compares them with the committed catalog. It catches missing/unexpected entries and stale auth/service IDs without loading the executable registry in client code. @@ -419,9 +423,10 @@ After fixing, confirm: 4. Derived artifacts regenerated and their diffs reviewed (see above) 5. `bun run integration-catalog:check` passes 6. `bun run docs:check` passes -7. For OAuth or service-account changes, `bun test apps/sim/lib/integrations/availability.server.test.ts` passes -8. Re-read all modified files to verify fixes are correct -9. Any remaining unknown response schemas were explicitly reported to the user instead of guessed +7. For OAuth or service-account changes, `bun run deployment-config:check` passes +8. For OAuth or service-account changes, `bun run --cwd apps/sim test lib/integrations/availability.server.test.ts` passes +9. Re-read all modified files to verify fixes are correct +10. Any remaining unknown response schemas were explicitly reported to the user instead of guessed ## Checklist Summary @@ -437,7 +442,7 @@ After fixing, confirm: - [ ] Validated scope descriptions exist in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts` for all scopes - [ ] Validated OAuth `serviceId` resolves to the intended `OAUTH_CLIENT_CAPABILITIES` entry and all capability fields exist in the env schema - [ ] Validated service-account projection and deployment requirement against the canonical OAuth service config -- [ ] Regenerated `integrations.json` when block metadata changed and ran `bun run integration-catalog:check` +- [ ] Regenerated deployment config when block/OAuth metadata changed and ran both catalog checks - [ ] Validated pagination consistency across tools and block - [ ] Validated memory load safety using `.agents/skills/memory-load-check/SKILL.md` when tools list/search/download/import/export/batch data - [ ] Validated error handling (error checks, meaningful messages) diff --git a/.claude/rules/sim-integrations.md b/.claude/rules/sim-integrations.md index 0ac54ab9194..34231a900b9 100644 --- a/.claude/rules/sim-integrations.md +++ b/.claude/rules/sim-integrations.md @@ -17,4 +17,5 @@ The full authoring instructions — tool/block/icon/trigger scaffolding, SubBloc - Type coercions (`Number()`, etc.) belong in `tools.config.params` (runs at execution, after variable resolution) — never in `tools.config.tool` (runs at serialization; coercing there destroys dynamic `` references). - `canonicalParamId` must NOT match any subblock's `id`, must be unique **block-wide** (groups are keyed by canonical id across every subblock and hold exactly one `basicId`, so two operations that each need a pair need two different canonical ids), and all subblocks in a canonical group must share the same `required` status. The `inputs` section and the params function reference canonical IDs, not raw subblock IDs — the serializer deletes the subblock IDs and republishes the active member's value under the canonical ID. - A canonical pair carries ONE concept. For files that is upload (basic) + file reference (advanced), as in Gmail attachments (`blocks/blocks/gmail.ts`). Never overload the advanced side with alternate identifiers (URL, provider asset ID) — give those their own subblocks, mark mutually exclusive sources `required: false`, and enforce "exactly one" at execution. +- A sub-block's option list is EITHER `selectorKey` (a registered selector — the only way to load a remote list, and the only one that works off the canvas) OR `options` (a static array, or a pure function of the block's own values). Never fetch from a block definition, and never read the workflow stores there. A credential sub-block needs `canonicalParamId: 'oauthCredential'` for its dependants' selectors to resolve. A secret must never appear in a selector's `getQueryKey`. `bun run check:fork-dependent-coverage` fails a `dependsOn` under a credential/KB/table anchor that the fork sync modal cannot offer. - Blocks must also set the catalog/UI metadata fields `integrationType`, `tags`, `authMode`, `docsLink`, and export a `{Service}BlockMeta` — see the `/add-block` skill's BlockMeta section for details. diff --git a/.github/workflows/publish-sim-setup.yml b/.github/workflows/publish-sim-setup.yml new file mode 100644 index 00000000000..e8d9f181b19 --- /dev/null +++ b/.github/workflows/publish-sim-setup.yml @@ -0,0 +1,174 @@ +name: Publish Sim Setup Package + +on: + push: + branches: [main, staging, dev] + paths: + - 'packages/sim-setup/**' + - 'packages/deployment-config/**' + - 'packages/security/**' + - 'packages/utils/**' + - 'docker-compose.prod.yml' + - 'bun.lock' + +permissions: + contents: read + +concurrency: + group: publish-sim-setup-${{ github.ref }} + cancel-in-progress: false + +jobs: + publish-npm: + runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-4vcpu-ubuntu-2404' || 'ubuntu-latest' }} + timeout-minutes: 15 + steps: + - name: Checkout repository + uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 + + - name: Setup Bun + uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2 + with: + bun-version: 1.3.14 + + - name: Setup Node + uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6 + with: + node-version: '20' + + - name: Cache Bun dependencies + uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5 + with: + path: | + ~/.bun/install/cache + node_modules + **/node_modules + key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }} + restore-keys: | + ${{ runner.os }}-bun- + + - name: Install dependencies + run: bun install --frozen-lockfile --ignore-scripts + + - name: Verify npm authentication + env: + NPM_CONFIG_TOKEN: ${{ secrets.NPM_TOKEN }} + run: bun pm whoami + + - name: Check generated deployment config + run: bun run deployment-config:check + + - name: Run tests + working-directory: packages/sim-setup + run: bun run test + + - name: Type-check packages + run: | + bun run --cwd packages/deployment-config type-check + bun run --cwd packages/sim-setup type-check + + - name: Build package + working-directory: packages/sim-setup + run: bun run build + + - name: Resolve release channel + id: release + working-directory: packages/sim-setup + env: + BRANCH: ${{ github.ref_name }} + run: | + BASE_VERSION="$(bun -p "require('./package.json').version")" + if [[ ! "$BASE_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + echo "Package version must be a stable X.Y.Z base, got '$BASE_VERSION'." >&2 + exit 1 + fi + + case "$BRANCH" in + dev) + VERSION="${BASE_VERSION}-dev.${GITHUB_RUN_NUMBER}.${GITHUB_RUN_ATTEMPT}" + TAG="dev" + ;; + staging) + VERSION="${BASE_VERSION}-preview.${GITHUB_RUN_NUMBER}.${GITHUB_RUN_ATTEMPT}" + TAG="staging" + ;; + main) + VERSION="$BASE_VERSION" + TAG="latest" + ;; + *) + echo "Unsupported release branch '$BRANCH'." >&2 + exit 1 + ;; + esac + + bun pm pkg set "version=$VERSION" + RESOLVED_VERSION="$(bun -p "require('./package.json').version")" + if [ "$RESOLVED_VERSION" != "$VERSION" ]; then + echo "Version injection mismatch: wanted '$VERSION', got '$RESOLVED_VERSION'." >&2 + exit 1 + fi + + { + echo "version=$VERSION" + echo "tag=$TAG" + } >> "$GITHUB_OUTPUT" + + - name: Smoke-test packed Node bundle + working-directory: packages/sim-setup + run: | + set -euo pipefail + SMOKE_DIR="$(mktemp -d "$RUNNER_TEMP/sim-setup-smoke.XXXXXX")" + PACKAGE_PATH="$SMOKE_DIR/sim-setup.tgz" + bun pm pack --ignore-scripts --filename "$PACKAGE_PATH" --quiet + tar -xzf "$PACKAGE_PATH" -C "$SMOKE_DIR" + + if tar -tzf "$PACKAGE_PATH" | grep -Eq '^package/(apps|docker|helm|packages|scripts)/'; then + echo 'Packed setup package contains repository source directories.' >&2 + exit 1 + fi + test -x "$SMOKE_DIR/package/dist/index.js" + test -f "$SMOKE_DIR/package/dist/docker-compose.prod.yml" + if grep -Eq '^[[:space:]]+(build|context):' "$SMOKE_DIR/package/dist/docker-compose.prod.yml"; then + echo 'Production Compose asset contains a local build dependency.' >&2 + exit 1 + fi + + cd "$SMOKE_DIR" + node package/dist/index.js --version + node package/dist/index.js --help + for command in config add doctor start stop restart update status logs down reset; do + node package/dist/index.js "$command" --help > /dev/null + done + node package/dist/index.js add integration --help > /dev/null + if node package/dist/index.js --quik > /dev/null 2>&1; then + echo 'Packed setup CLI accepted an unknown option.' >&2 + exit 1 + fi + if node package/dist/index.js start extra > /dev/null 2>&1; then + echo 'Packed setup CLI accepted an extra lifecycle operand.' >&2 + exit 1 + fi + + - name: Verify version is unpublished + working-directory: packages/sim-setup + env: + VERSION: ${{ steps.release.outputs.version }} + run: | + if bun pm view "sim-setup@$VERSION" version > /dev/null 2>&1; then + echo "sim-setup@$VERSION is already published. Bump packages/sim-setup/package.json before releasing another build." >&2 + exit 1 + fi + + - name: Publish to npm + working-directory: packages/sim-setup + env: + NPM_CONFIG_TOKEN: ${{ secrets.NPM_TOKEN }} + NPM_TAG: ${{ steps.release.outputs.tag }} + run: bun publish --access public --tag "$NPM_TAG" --no-save + + - name: Summarize release + env: + VERSION: ${{ steps.release.outputs.version }} + NPM_TAG: ${{ steps.release.outputs.tag }} + run: echo "Published sim-setup@$VERSION with the '$NPM_TAG' tag." diff --git a/README.md b/README.md index 5967bfa7c12..2d9b86ca5db 100644 --- a/README.md +++ b/README.md @@ -27,9 +27,7 @@ ### Self-hosted ```bash -git clone https://github.com/simstudioai/sim.git && cd sim -bun install -bun run setup +npx sim-setup ``` Open [http://localhost:3000](http://localhost:3000) @@ -72,56 +70,52 @@ Open [http://localhost:3000](http://localhost:3000) ## Self-hosting -**Requirements:** [Bun](https://bun.sh/) and [Docker](https://www.docker.com/). +**Requirements:** [Node.js 20+](https://nodejs.org/) and [Docker](https://www.docker.com/). -`bun run setup` is an interactive wizard: it provisions the database, generates secrets, writes your `.env` files, connects a Chat API key, and starts Sim the way you choose: - -- **Local dev** — run from source to contribute or hack on Sim -- **Docker Compose** — a self-contained instance for testing self-hosting -- **Kubernetes (Helm)** — deploy to a local cluster +`npx sim-setup` is an interactive wizard that creates a small `sim/` deployment directory, provisions the database, generates secrets, writes `.env`, connects a Chat API key, and starts the published Sim images with Docker Compose. It does not clone the repository. When it finishes, open [http://localhost:3000](http://localhost:3000). +Inside a cloned Sim repository, run `bun run sim-setup` to unlock the source-only local development and Kubernetes modes. + Reconfigure an optional capability without rerunning the full wizard: ```bash -bun run setup status -bun run setup email -bun run setup storage -bun run setup sandbox -bun run setup jobs -bun run setup cache -bun run setup knowledge -bun run setup llm -bun run setup integration slack +npx sim-setup config +npx sim-setup add email +npx sim-setup add storage +npx sim-setup add sandbox +npx sim-setup add jobs +npx sim-setup add cache +npx sim-setup add knowledge +npx sim-setup add llm +npx sim-setup add integration slack ``` -`bun run setup status` detects the effective local-dev, Docker Compose, or current-context +`npx sim-setup config` detects the effective local-dev, Docker Compose, or current-context Helm configuration and reports configured, missing, or invalid capabilities and OAuth -integrations without printing credential values. This is separate from `bun run sim status`, +integrations without printing credential values. This is separate from `npx sim-setup status`, which reports whether installed services are running and healthy. -Manage your install with `bun run sim`: +Manage your install from its directory: ```bash -bun run sim start | stop | restart # bring your install up / down / cycle -bun run sim update # pull/rebuild and apply Compose images -bun run sim status # what's installed and healthy -bun run sim logs # follow logs -bun run sim doctor # diagnose configuration problems -bun run sim down # remove containers (data kept) -bun run sim reset # archive .env and wipe managed data +npx sim-setup start | stop | restart # bring your install up / down / cycle +npx sim-setup update # pull and apply Compose images +npx sim-setup status # what's installed and healthy +npx sim-setup logs # follow logs +npx sim-setup doctor # diagnose configuration problems +npx sim-setup down # remove containers (data kept) +npx sim-setup reset # archive .env and wipe managed data ``` -`sim` detects how you're running (Docker Compose, local dev, or Kubernetes) and acts accordingly. - -Prefer a bare `sim`? Run `bun link` once — but note `sim` lands in `~/.bun/bin`, which Homebrew's bun doesn't add to your PATH, so you may need `export PATH="$HOME/.bun/bin:$PATH"` in your shell profile. +The setup package detects how you're running and acts accordingly. Use `--dir ` to create or manage a deployment somewhere other than `./sim`. Sim also supports local models via [Ollama](https://ollama.ai) and [vLLM](https://docs.vllm.ai/). See the [self-hosting docs](https://docs.sim.ai/self-hosting/docker) for details. ## Chat API Keys -Chat is a Sim-managed service. `bun run setup` connects a Chat API key for you — sign in when it opens your browser and the key is stored automatically. To view, create, or revoke keys later, go to [sim.ai/selfhost/settings/chat-keys](https://sim.ai/selfhost/settings/chat-keys). +Chat is a Sim-managed service. `npx sim-setup` connects a Chat API key for you — sign in when it opens your browser and the key is stored automatically. To view, create, or revoke keys later, go to [sim.ai/selfhost/settings/chat-keys](https://sim.ai/selfhost/settings/chat-keys). ## Environment Variables diff --git a/apps/docs/components/icons.tsx b/apps/docs/components/icons.tsx index 01f30f3e399..35c5c1637c1 100644 --- a/apps/docs/components/icons.tsx +++ b/apps/docs/components/icons.tsx @@ -50,39 +50,39 @@ export function AgentPhoneIcon(props: SVGProps) { @@ -675,11 +675,11 @@ export function SlackIcon(props: SVGProps) { fill='#E01E5A' /> ) { - - + + @@ -754,6 +754,38 @@ export function GithubOutlineIcon(props: SVGProps) { ) } +export function BitbucketIcon(props: SVGProps) { + const id = useId() + const gradientId = `bitbucket_original_a_${id}` + + return ( + + + + + + + + + + + ) +} + export function GitLabIcon(props: SVGProps) { return ( @@ -915,7 +947,7 @@ export function ConnectIcon(props: SVGProps) { xmlns='http://www.w3.org/2000/svg' > @@ -969,7 +1001,7 @@ export function PersonaIcon(props: SVGProps) { {...props} > @@ -1489,15 +1521,13 @@ export function InstagramIcon(props: SVGProps) { export function CrunchbaseIcon(props: SVGProps) { return ( - - + + ) } @@ -1513,7 +1543,7 @@ export function InputIcon(props: SVGProps) { xmlns='http://www.w3.org/2000/svg' > @@ -1562,23 +1592,23 @@ export function ProspeoIcon(props: SVGProps) { @@ -1721,7 +1751,7 @@ export function OpenAIIcon(props: SVGProps) { xmlns='http://www.w3.org/2000/svg' > @@ -1753,32 +1783,29 @@ export function RB2BIcon(props: SVGProps) { return ( - - - - + + + + + + - + + + + - - - - - - + @@ -1896,11 +1923,11 @@ export function GoogleAppsheetIcon(props: SVGProps) { - - + + ) @@ -2267,11 +2294,11 @@ export function AtlassianIcon(props: SVGProps) { ) @@ -2355,15 +2382,15 @@ export function ConvexIcon(props: SVGProps) { xmlns='http://www.w3.org/2000/svg' > @@ -2386,11 +2413,11 @@ export function SendblueIcon(props: SVGProps) { ) @@ -2529,15 +2556,15 @@ export function MintlifyIcon(props: SVGProps) { return ( @@ -2757,7 +2784,7 @@ export function ExtendIcon(props: SVGProps) { return ( ) { /> @@ -2799,13 +2826,13 @@ export function FindymailIcon(props: SVGProps) { @@ -2842,19 +2869,19 @@ export function ZeroBounceIcon(props: SVGProps) { @@ -3057,7 +3084,7 @@ export function LinearIcon(props: React.SVGProps) { > ) @@ -3183,7 +3210,7 @@ export function ThriveIcon(props: SVGProps) { return ( @@ -4515,18 +4542,15 @@ export function QuartrIcon(props: SVGProps) { - + - + ) @@ -4793,47 +4817,47 @@ export function MicrosoftOneDriveIcon(props: SVGProps) { ) @@ -5695,6 +5719,22 @@ export function Neo4jIcon(props: SVGProps) { ) } +export function CbInsightsIcon(props: SVGProps) { + return ( + + + + + + ) +} + export function CalendlyIcon(props: SVGProps) { return ( @@ -5843,23 +5883,23 @@ export function PosthogIcon(props: SVGProps) { xmlns='http://www.w3.org/2000/svg' > @@ -6019,7 +6059,7 @@ export function ZendeskIcon(props: SVGProps) { > @@ -6049,17 +6089,17 @@ export function ZoomInfoIcon(props: SVGProps) { > - + @@ -6274,27 +6314,27 @@ export function DynatraceIcon(props: SVGProps) { ) @@ -6549,7 +6589,7 @@ export function CodePipelineIcon(props: SVGProps) { transform='translate(40, 40) scale(1.25) translate(-40, -40)' > @@ -6741,11 +6781,11 @@ export function GitlabIcon(props: SVGProps) { ) { /> ) @@ -6869,25 +6909,25 @@ export function DaytonaIcon(props: SVGProps) { ) { y='12.9094' width='20.6556' height='8.54718' - transform='rotate(90 22.1582 12.9094)' + transform='rotate(90 22.16 12.91)' fill='currentColor' /> ) { y='42.825' width='25.6415' height='8.54718' - transform='rotate(90 52.0732 42.825)' + transform='rotate(90 52.07 42.83)' fill='currentColor' /> @@ -7180,15 +7220,15 @@ export function DowndetectorIcon(props: SVGProps) { @@ -7286,7 +7326,7 @@ export function GranolaIcon(props: SVGProps) { > ) @@ -7339,19 +7379,19 @@ export function GreptileIcon(props: SVGProps) { return ( @@ -8534,7 +8574,7 @@ export function VantaIcon(props: SVGProps) { ) { @@ -8905,31 +8945,31 @@ export function LeadMagicIcon(props: SVGProps) { @@ -8959,11 +8999,11 @@ export function IcypeasIcon(props: SVGProps) { @@ -9107,7 +9147,7 @@ export function RetoolIcon(props: SVGProps) { ) @@ -9172,51 +9212,51 @@ export function JupyterIcon(props: SVGProps) { @@ -9242,13 +9282,13 @@ export function RocketlaneIcon(props: SVGProps) { @@ -9269,7 +9309,7 @@ export function LogfireIcon(props: SVGProps) { role='img' xmlns='http://www.w3.org/2000/svg' > - + ) } @@ -9302,21 +9342,21 @@ export function SmartleadIcon(props: SVGProps) { > @@ -9340,3 +9380,18 @@ export function ZohoDeskIcon(props: SVGProps) { ) } + +export function PitchBookIcon(props: SVGProps) { + return ( + + ) +} diff --git a/apps/docs/components/ui/icon-mapping.ts b/apps/docs/components/ui/icon-mapping.ts index ba0735d39f2..cbf910d4b24 100644 --- a/apps/docs/components/ui/icon-mapping.ts +++ b/apps/docs/components/ui/icon-mapping.ts @@ -24,6 +24,7 @@ import { AttioIcon, AzureDataExplorerIcon, AzureIcon, + BitbucketIcon, BoxCompanyIcon, BrainIcon, BrandfetchIcon, @@ -33,6 +34,7 @@ import { BufferIcon, CalComIcon, CalendlyIcon, + CbInsightsIcon, CirclebackIcon, ClaudeIcon, ClayIcon, @@ -47,6 +49,7 @@ import { ContextDevIcon, ConvexIcon, CrowdStrikeIcon, + CrunchbaseIcon, CursorIcon, DagsterIcon, DatabricksIcon, @@ -175,6 +178,7 @@ import { PersonaIcon, PineconeIcon, PipedriveIcon, + PitchBookIcon, PolymarketIcon, PostgresIcon, PosthogIcon, @@ -285,6 +289,7 @@ export const blockTypeToIconMap: Record = { attio: AttioIcon, azure_data_explorer: AzureDataExplorerIcon, azure_devops: AzureIcon, + bitbucket: BitbucketIcon, box: BoxCompanyIcon, brandfetch: BrandfetchIcon, brex: BrexIcon, @@ -293,6 +298,7 @@ export const blockTypeToIconMap: Record = { buffer: BufferIcon, calcom: CalComIcon, calendly: CalendlyIcon, + cbinsights: CbInsightsIcon, circleback: CirclebackIcon, clay: ClayIcon, clerk: ClerkIcon, @@ -307,6 +313,7 @@ export const blockTypeToIconMap: Record = { context_dev: ContextDevIcon, convex: ConvexIcon, crowdstrike: CrowdStrikeIcon, + crunchbase: CrunchbaseIcon, cursor: CursorIcon, cursor_v2: CursorIcon, dagster: DagsterIcon, @@ -464,6 +471,7 @@ export const blockTypeToIconMap: Record = { persona: PersonaIcon, pinecone: PineconeIcon, pipedrive: PipedriveIcon, + pitchbook: PitchBookIcon, polymarket: PolymarketIcon, postgresql: PostgresIcon, posthog: PosthogIcon, diff --git a/apps/docs/content/docs/en/integrations/bitbucket.mdx b/apps/docs/content/docs/en/integrations/bitbucket.mdx new file mode 100644 index 00000000000..8d7529ce0c8 --- /dev/null +++ b/apps/docs/content/docs/en/integrations/bitbucket.mdx @@ -0,0 +1,1548 @@ +--- +title: Bitbucket +description: Work with Bitbucket Cloud repositories, pull requests, and pipelines +--- + +import { BlockInfoCard } from "@/components/ui/block-info-card" + + + +## Usage Instructions + +Connect Bitbucket Cloud to inspect repositories and source, collaborate on pull requests, and diagnose or control pipelines. This action integration uses OAuth and does not create webhooks or triggers. + + + +## Actions + +### Bitbucket List Workspaces + +List Bitbucket Cloud workspaces available to the authenticated account + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `sort` | string | No | Workspace sort field; Bitbucket currently supports slug | +| `administrator` | boolean | No | Filter by whether the caller is a workspace administrator | +| `nextUrl` | string | No | Opaque next-page URL returned by a previous Bitbucket call | +| `pageLen` | number | No | Results per page \(1-100\) | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `page` | object | Pagination information | +| ↳ `size` | number | Total result count reported by Bitbucket | +| ↳ `page` | number | Current page number | +| ↳ `pageLen` | number | Number of results requested per page | +| ↳ `nextUrl` | string | Validated URL for the next page | +| ↳ `previousUrl` | string | Validated URL for the previous page | +| `items` | array | Workspace access records | +| ↳ `type` | string | Bitbucket workspace-access object type | +| ↳ `slug` | string | Workspace slug | +| ↳ `uuid` | string | Workspace UUID | +| ↳ `administrator` | boolean | Whether the caller administers the workspace | +| ↳ `selfUrl` | string | Workspace API URL | +| ↳ `avatarUrl` | string | Workspace avatar URL | + +### Bitbucket List Repositories + +List repositories in a Bitbucket Cloud workspace + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `role` | string | No | Caller role filter: admin, contributor, member, or owner | +| `q` | string | No | Bitbucket filtering expression | +| `sort` | string | No | Bitbucket sort expression | +| `nextUrl` | string | No | Opaque next-page URL returned by a previous Bitbucket call | +| `pageLen` | number | No | Results per page \(1-100\) | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `page` | object | Pagination information | +| ↳ `size` | number | Total result count reported by Bitbucket | +| ↳ `page` | number | Current page number | +| ↳ `pageLen` | number | Number of results requested per page | +| ↳ `nextUrl` | string | Validated URL for the next page | +| ↳ `previousUrl` | string | Validated URL for the previous page | +| `items` | array | Repositories | +| ↳ `type` | string | Bitbucket repository object type | +| ↳ `uuid` | string | Repository UUID | +| ↳ `slug` | string | Repository slug | +| ↳ `name` | string | Repository name | +| ↳ `fullName` | string | Workspace and repository full name | +| ↳ `description` | string | Repository description | +| ↳ `isPrivate` | boolean | Whether the repository is private | +| ↳ `scm` | string | Source control system | +| ↳ `language` | string | Primary repository language | +| ↳ `size` | number | Repository size in bytes | +| ↳ `createdOn` | string | Repository creation timestamp | +| ↳ `updatedOn` | string | Repository update timestamp | +| ↳ `mainBranch` | string | Main branch name | +| ↳ `owner` | object | Repository owner | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `project` | object | Containing Bitbucket project | +| ↳ `uuid` | string | Project UUID | +| ↳ `key` | string | Project key | +| ↳ `name` | string | Project name | +| ↳ `selfUrl` | string | Repository API URL | +| ↳ `htmlUrl` | string | Repository web URL | + +### Bitbucket Get Repository + +Get a Bitbucket Cloud repository + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `repository` | object | Repository details | +| ↳ `type` | string | Bitbucket repository object type | +| ↳ `uuid` | string | Repository UUID | +| ↳ `slug` | string | Repository slug | +| ↳ `name` | string | Repository name | +| ↳ `fullName` | string | Workspace and repository full name | +| ↳ `description` | string | Repository description | +| ↳ `isPrivate` | boolean | Whether the repository is private | +| ↳ `scm` | string | Source control system | +| ↳ `language` | string | Primary repository language | +| ↳ `size` | number | Repository size in bytes | +| ↳ `createdOn` | string | Repository creation timestamp | +| ↳ `updatedOn` | string | Repository update timestamp | +| ↳ `mainBranch` | string | Main branch name | +| ↳ `owner` | object | Repository owner | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `project` | object | Containing Bitbucket project | +| ↳ `uuid` | string | Project UUID | +| ↳ `key` | string | Project key | +| ↳ `name` | string | Project name | +| ↳ `selfUrl` | string | Repository API URL | +| ↳ `htmlUrl` | string | Repository web URL | + +### Bitbucket List Branches + +List branches in a Bitbucket Cloud repository + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `q` | string | No | Bitbucket branch filtering expression | +| `sort` | string | No | Bitbucket branch sort expression | +| `nextUrl` | string | No | Opaque next-page URL returned by a previous Bitbucket call | +| `pageLen` | number | No | Results per page \(1-100\) | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `page` | object | Pagination information | +| ↳ `size` | number | Total result count reported by Bitbucket | +| ↳ `page` | number | Current page number | +| ↳ `pageLen` | number | Number of results requested per page | +| ↳ `nextUrl` | string | Validated URL for the next page | +| ↳ `previousUrl` | string | Validated URL for the previous page | +| `items` | array | Branches | +| ↳ `type` | string | Bitbucket branch object type | +| ↳ `name` | string | Branch name | +| ↳ `target` | object | Commit targeted by the branch | +| ↳ `type` | string | Bitbucket commit object type | +| ↳ `hash` | string | Commit hash | +| ↳ `date` | string | Commit timestamp | +| ↳ `message` | string | Full commit message | +| ↳ `summary` | string | Raw commit summary | +| ↳ `authorRaw` | string | Raw author value stored by Git | +| ↳ `author` | object | Matched Bitbucket account, when available | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `committerRaw` | string | Raw committer value stored by Git | +| ↳ `committer` | object | Matched Bitbucket committer account, when available | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `parents` | array | Parent commits | +| ↳ `hash` | string | Parent commit hash | +| ↳ `selfUrl` | string | Commit API URL | +| ↳ `htmlUrl` | string | Commit web URL | +| ↳ `mergeStrategies` | array | Merge strategies available for the branch | +| ↳ `defaultMergeStrategy` | string | Default merge strategy | +| ↳ `selfUrl` | string | Branch API URL | +| ↳ `htmlUrl` | string | Branch web URL | + +### Bitbucket Create Branch + +Create a branch at a commit hash or existing ref + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `name` | string | Yes | New branch name without refs/heads prefix | +| `target` | string | Yes | Full commit hash or existing ref to target | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `branch` | object | Created branch | +| ↳ `type` | string | Bitbucket branch object type | +| ↳ `name` | string | Branch name | +| ↳ `target` | object | Commit targeted by the branch | +| ↳ `type` | string | Bitbucket commit object type | +| ↳ `hash` | string | Commit hash | +| ↳ `date` | string | Commit timestamp | +| ↳ `message` | string | Full commit message | +| ↳ `summary` | string | Raw commit summary | +| ↳ `authorRaw` | string | Raw author value stored by Git | +| ↳ `author` | object | Matched Bitbucket account, when available | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `committerRaw` | string | Raw committer value stored by Git | +| ↳ `committer` | object | Matched Bitbucket committer account, when available | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `parents` | array | Parent commits | +| ↳ `hash` | string | Parent commit hash | +| ↳ `selfUrl` | string | Commit API URL | +| ↳ `htmlUrl` | string | Commit web URL | +| ↳ `mergeStrategies` | array | Merge strategies available for the branch | +| ↳ `defaultMergeStrategy` | string | Default merge strategy | +| ↳ `selfUrl` | string | Branch API URL | +| ↳ `htmlUrl` | string | Branch web URL | + +### Bitbucket Delete Branch + +Delete a branch from a Bitbucket Cloud repository + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `name` | string | Yes | Branch name to delete | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `deleted` | boolean | Whether the branch was deleted | + +### Bitbucket List Commits + +List repository commits in reverse chronological order + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `nextUrl` | string | No | Opaque next-page URL returned by a previous Bitbucket call | +| `pageLen` | number | No | Results per page \(1-100\) | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `page` | object | Pagination information | +| ↳ `size` | number | Total result count reported by Bitbucket | +| ↳ `page` | number | Current page number | +| ↳ `pageLen` | number | Number of results requested per page | +| ↳ `nextUrl` | string | Validated URL for the next page | +| ↳ `previousUrl` | string | Validated URL for the previous page | +| `items` | array | Commits | +| ↳ `type` | string | Bitbucket commit object type | +| ↳ `hash` | string | Commit hash | +| ↳ `date` | string | Commit timestamp | +| ↳ `message` | string | Full commit message | +| ↳ `summary` | string | Raw commit summary | +| ↳ `authorRaw` | string | Raw author value stored by Git | +| ↳ `author` | object | Matched Bitbucket account, when available | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `committerRaw` | string | Raw committer value stored by Git | +| ↳ `committer` | object | Matched Bitbucket committer account, when available | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `parents` | array | Parent commits | +| ↳ `hash` | string | Parent commit hash | +| ↳ `selfUrl` | string | Commit API URL | +| ↳ `htmlUrl` | string | Commit web URL | + +### Bitbucket Get Commit + +Get a repository commit by its full SHA-1 + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `commit` | string | Yes | Full 40-character commit SHA-1 | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `commit` | object | Commit details | +| ↳ `type` | string | Bitbucket commit object type | +| ↳ `hash` | string | Commit hash | +| ↳ `date` | string | Commit timestamp | +| ↳ `message` | string | Full commit message | +| ↳ `summary` | string | Raw commit summary | +| ↳ `authorRaw` | string | Raw author value stored by Git | +| ↳ `author` | object | Matched Bitbucket account, when available | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `committerRaw` | string | Raw committer value stored by Git | +| ↳ `committer` | object | Matched Bitbucket committer account, when available | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `parents` | array | Parent commits | +| ↳ `hash` | string | Parent commit hash | +| ↳ `selfUrl` | string | Commit API URL | +| ↳ `htmlUrl` | string | Commit web URL | + +### Bitbucket List Directory + +List one shallow repository directory at a full commit SHA-1 + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `commit` | string | Yes | Full 40-character commit SHA-1 | +| `path` | string | No | Repository-relative directory path; omit for the root | +| `q` | string | No | Bitbucket tree-entry filtering expression | +| `sort` | string | No | Bitbucket tree-entry sort expression | +| `nextUrl` | string | No | Opaque next-page URL returned by a previous Bitbucket call | +| `pageLen` | number | No | Results per page \(1-100\) | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `page` | object | Pagination information | +| ↳ `size` | number | Total result count reported by Bitbucket | +| ↳ `page` | number | Current page number | +| ↳ `pageLen` | number | Number of results requested per page | +| ↳ `nextUrl` | string | Validated URL for the next page | +| ↳ `previousUrl` | string | Validated URL for the previous page | +| `items` | array | Directory entries | +| ↳ `type` | string | Entry type, such as commit_file or commit_directory | +| ↳ `path` | string | Repository-relative path | +| ↳ `commitHash` | string | Resolved commit hash | +| ↳ `size` | number | File size in bytes when the entry is a file | +| ↳ `attributes` | array | File attributes when the entry is a file | +| ↳ `isBinary` | boolean | Whether file attributes include the binary marker | +| ↳ `selfUrl` | string | Source API URL | +| ↳ `metadataUrl` | string | Source metadata API URL | + +### Bitbucket Get File Metadata + +Inspect file size and attributes at a full repository commit SHA-1 + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `commit` | string | Yes | Full 40-character commit SHA-1 | +| `path` | string | Yes | Repository-relative file path | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `file` | object | File metadata | +| ↳ `type` | string | Entry type \(commit_file\) | +| ↳ `path` | string | Repository-relative path | +| ↳ `commitHash` | string | Resolved commit hash | +| ↳ `escapedPath` | string | Escaped display path | +| ↳ `size` | number | File size in bytes | +| ↳ `attributes` | array | File attributes reported by Bitbucket | +| ↳ `isBinary` | boolean | Whether the documented attributes include the binary marker | + +### Bitbucket Get File + +Read bounded UTF-8 text from a file at a full repository commit SHA-1 + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `commit` | string | Yes | Full 40-character commit SHA-1 | +| `path` | string | Yes | Repository-relative file path | +| `maxCharacters` | number | No | Maximum text characters to return \(1-500000\) | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `content` | string | Bounded UTF-8 file text; null for binary content | +| `binary` | boolean | Whether documented metadata identifies binary content; null when unknown | +| `truncated` | boolean | Whether later content was omitted; null when binary size is unknown | +| `returnedBytes` | number | Provider bytes read for the returned file | +| `fullBytes` | number | Full file byte size when reported | +| `contentType` | string | Response MIME type | + +### Bitbucket List Pull Requests + +List pull requests in a Bitbucket Cloud repository + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `state` | string | No | State filter: OPEN, MERGED, DECLINED, or SUPERSEDED | +| `q` | string | No | Bitbucket pull request filtering expression | +| `sort` | string | No | Bitbucket pull request sort expression | +| `nextUrl` | string | No | Opaque next-page URL returned by a previous Bitbucket call | +| `pageLen` | number | No | Results per page \(1-100\) | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `page` | object | Pagination information | +| ↳ `size` | number | Total result count reported by Bitbucket | +| ↳ `page` | number | Current page number | +| ↳ `pageLen` | number | Number of results requested per page | +| ↳ `nextUrl` | string | Validated URL for the next page | +| ↳ `previousUrl` | string | Validated URL for the previous page | +| `items` | array | Pull requests | +| ↳ `type` | string | Bitbucket pull request object type | +| ↳ `id` | number | Repository-scoped pull request ID | +| ↳ `title` | string | Pull request title | +| ↳ `description` | string | Pull request description | +| ↳ `state` | string | Pull request state | +| ↳ `draft` | boolean | Whether the pull request is a draft | +| ↳ `queued` | boolean | Whether the pull request is queued | +| ↳ `author` | object | Pull request author | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `closedBy` | object | Account that closed the pull request | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `source` | object | Source endpoint | +| ↳ `branchName` | string | Branch name | +| ↳ `commitHash` | string | Commit hash | +| ↳ `repositoryUuid` | string | Repository UUID | +| ↳ `repositoryFullName` | string | Repository full name | +| ↳ `destination` | object | Destination endpoint | +| ↳ `branchName` | string | Branch name | +| ↳ `commitHash` | string | Commit hash | +| ↳ `repositoryUuid` | string | Repository UUID | +| ↳ `repositoryFullName` | string | Repository full name | +| ↳ `mergeCommitHash` | string | Merge commit hash | +| ↳ `commentCount` | number | Comment count | +| ↳ `taskCount` | number | Open task count | +| ↳ `closeSourceBranch` | boolean | Whether merging closes the source branch | +| ↳ `reason` | string | Reason the pull request was declined | +| ↳ `createdOn` | string | Creation timestamp | +| ↳ `updatedOn` | string | Update timestamp | +| ↳ `reviewers` | array | Explicit reviewers | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `participants` | array | Pull request participants | +| ↳ `type` | string | Bitbucket participant object type | +| ↳ `user` | object | Participating account | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `role` | string | Participant role | +| ↳ `approved` | boolean | Whether the participant approved | +| ↳ `state` | string | Review state | +| ↳ `participatedOn` | string | Timestamp of the participant action | +| ↳ `selfUrl` | string | Pull request API URL | +| ↳ `htmlUrl` | string | Pull request web URL | + +### Bitbucket Get Pull Request + +Get a pull request by repository-scoped ID + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `prId` | number | Yes | Repository-scoped pull request ID | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `pullRequest` | object | Pull request details | +| ↳ `type` | string | Bitbucket pull request object type | +| ↳ `id` | number | Repository-scoped pull request ID | +| ↳ `title` | string | Pull request title | +| ↳ `description` | string | Pull request description | +| ↳ `state` | string | Pull request state | +| ↳ `draft` | boolean | Whether the pull request is a draft | +| ↳ `queued` | boolean | Whether the pull request is queued | +| ↳ `author` | object | Pull request author | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `closedBy` | object | Account that closed the pull request | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `source` | object | Source endpoint | +| ↳ `branchName` | string | Branch name | +| ↳ `commitHash` | string | Commit hash | +| ↳ `repositoryUuid` | string | Repository UUID | +| ↳ `repositoryFullName` | string | Repository full name | +| ↳ `destination` | object | Destination endpoint | +| ↳ `branchName` | string | Branch name | +| ↳ `commitHash` | string | Commit hash | +| ↳ `repositoryUuid` | string | Repository UUID | +| ↳ `repositoryFullName` | string | Repository full name | +| ↳ `mergeCommitHash` | string | Merge commit hash | +| ↳ `commentCount` | number | Comment count | +| ↳ `taskCount` | number | Open task count | +| ↳ `closeSourceBranch` | boolean | Whether merging closes the source branch | +| ↳ `reason` | string | Reason the pull request was declined | +| ↳ `createdOn` | string | Creation timestamp | +| ↳ `updatedOn` | string | Update timestamp | +| ↳ `reviewers` | array | Explicit reviewers | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `participants` | array | Pull request participants | +| ↳ `type` | string | Bitbucket participant object type | +| ↳ `user` | object | Participating account | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `role` | string | Participant role | +| ↳ `approved` | boolean | Whether the participant approved | +| ↳ `state` | string | Review state | +| ↳ `participatedOn` | string | Timestamp of the participant action | +| ↳ `selfUrl` | string | Pull request API URL | +| ↳ `htmlUrl` | string | Pull request web URL | + +### Bitbucket Create Pull Request + +Create a pull request between repository branches + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `title` | string | Yes | Pull request title | +| `sourceBranch` | string | Yes | Source branch name | +| `destinationBranch` | string | Yes | Destination branch name | +| `description` | string | No | Pull request description | +| `closeSourceBranch` | boolean | No | Close the source branch after merge | +| `draft` | boolean | No | Create the pull request as a draft | +| `reviewerUuids` | array | No | Bitbucket account UUIDs to add as reviewers | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `pullRequest` | object | Created pull request | +| ↳ `type` | string | Bitbucket pull request object type | +| ↳ `id` | number | Repository-scoped pull request ID | +| ↳ `title` | string | Pull request title | +| ↳ `description` | string | Pull request description | +| ↳ `state` | string | Pull request state | +| ↳ `draft` | boolean | Whether the pull request is a draft | +| ↳ `queued` | boolean | Whether the pull request is queued | +| ↳ `author` | object | Pull request author | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `closedBy` | object | Account that closed the pull request | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `source` | object | Source endpoint | +| ↳ `branchName` | string | Branch name | +| ↳ `commitHash` | string | Commit hash | +| ↳ `repositoryUuid` | string | Repository UUID | +| ↳ `repositoryFullName` | string | Repository full name | +| ↳ `destination` | object | Destination endpoint | +| ↳ `branchName` | string | Branch name | +| ↳ `commitHash` | string | Commit hash | +| ↳ `repositoryUuid` | string | Repository UUID | +| ↳ `repositoryFullName` | string | Repository full name | +| ↳ `mergeCommitHash` | string | Merge commit hash | +| ↳ `commentCount` | number | Comment count | +| ↳ `taskCount` | number | Open task count | +| ↳ `closeSourceBranch` | boolean | Whether merging closes the source branch | +| ↳ `reason` | string | Reason the pull request was declined | +| ↳ `createdOn` | string | Creation timestamp | +| ↳ `updatedOn` | string | Update timestamp | +| ↳ `reviewers` | array | Explicit reviewers | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `participants` | array | Pull request participants | +| ↳ `type` | string | Bitbucket participant object type | +| ↳ `user` | object | Participating account | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `role` | string | Participant role | +| ↳ `approved` | boolean | Whether the participant approved | +| ↳ `state` | string | Review state | +| ↳ `participatedOn` | string | Timestamp of the participant action | +| ↳ `selfUrl` | string | Pull request API URL | +| ↳ `htmlUrl` | string | Pull request web URL | + +### Bitbucket Merge Pull Request + +Start an asynchronous pull request merge and return a task to poll when needed + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `prId` | number | Yes | Repository-scoped pull request ID | +| `mergeStrategy` | string | No | Merge strategy: merge_commit, squash, fast_forward, squash_fast_forward, rebase_fast_forward, or rebase_merge | +| `message` | string | No | Merge commit message \(maximum 128 KiB encoded as UTF-8\) | +| `closeSourceBranch` | boolean | No | Delete the source branch after merging | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `status` | string | Whether the merge completed or remains pending | +| `taskId` | string | Async merge task ID | +| `taskUrl` | string | Validated task polling URL | +| `pullRequest` | object | Merged pull request when completed synchronously | +| ↳ `type` | string | Bitbucket pull request object type | +| ↳ `id` | number | Repository-scoped pull request ID | +| ↳ `title` | string | Pull request title | +| ↳ `description` | string | Pull request description | +| ↳ `state` | string | Pull request state | +| ↳ `draft` | boolean | Whether the pull request is a draft | +| ↳ `queued` | boolean | Whether the pull request is queued | +| ↳ `author` | object | Pull request author | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `closedBy` | object | Account that closed the pull request | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `source` | object | Source endpoint | +| ↳ `branchName` | string | Branch name | +| ↳ `commitHash` | string | Commit hash | +| ↳ `repositoryUuid` | string | Repository UUID | +| ↳ `repositoryFullName` | string | Repository full name | +| ↳ `destination` | object | Destination endpoint | +| ↳ `branchName` | string | Branch name | +| ↳ `commitHash` | string | Commit hash | +| ↳ `repositoryUuid` | string | Repository UUID | +| ↳ `repositoryFullName` | string | Repository full name | +| ↳ `mergeCommitHash` | string | Merge commit hash | +| ↳ `commentCount` | number | Comment count | +| ↳ `taskCount` | number | Open task count | +| ↳ `closeSourceBranch` | boolean | Whether merging closes the source branch | +| ↳ `reason` | string | Reason the pull request was declined | +| ↳ `createdOn` | string | Creation timestamp | +| ↳ `updatedOn` | string | Update timestamp | +| ↳ `reviewers` | array | Explicit reviewers | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `participants` | array | Pull request participants | +| ↳ `type` | string | Bitbucket participant object type | +| ↳ `user` | object | Participating account | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `role` | string | Participant role | +| ↳ `approved` | boolean | Whether the participant approved | +| ↳ `state` | string | Review state | +| ↳ `participatedOn` | string | Timestamp of the participant action | +| ↳ `selfUrl` | string | Pull request API URL | +| ↳ `htmlUrl` | string | Pull request web URL | + +### Bitbucket Get Merge Task Status + +Poll the status of an asynchronous pull request merge task + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `prId` | number | Yes | Repository-scoped pull request ID | +| `taskId` | string | Yes | Merge task ID returned by Bitbucket Merge Pull Request | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `taskStatus` | string | PENDING or SUCCESS | +| `selfUrl` | string | Merge task API URL | +| `mergeResult` | object | Merged pull request when the task succeeds | +| ↳ `type` | string | Bitbucket pull request object type | +| ↳ `id` | number | Repository-scoped pull request ID | +| ↳ `title` | string | Pull request title | +| ↳ `description` | string | Pull request description | +| ↳ `state` | string | Pull request state | +| ↳ `draft` | boolean | Whether the pull request is a draft | +| ↳ `queued` | boolean | Whether the pull request is queued | +| ↳ `author` | object | Pull request author | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `closedBy` | object | Account that closed the pull request | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `source` | object | Source endpoint | +| ↳ `branchName` | string | Branch name | +| ↳ `commitHash` | string | Commit hash | +| ↳ `repositoryUuid` | string | Repository UUID | +| ↳ `repositoryFullName` | string | Repository full name | +| ↳ `destination` | object | Destination endpoint | +| ↳ `branchName` | string | Branch name | +| ↳ `commitHash` | string | Commit hash | +| ↳ `repositoryUuid` | string | Repository UUID | +| ↳ `repositoryFullName` | string | Repository full name | +| ↳ `mergeCommitHash` | string | Merge commit hash | +| ↳ `commentCount` | number | Comment count | +| ↳ `taskCount` | number | Open task count | +| ↳ `closeSourceBranch` | boolean | Whether merging closes the source branch | +| ↳ `reason` | string | Reason the pull request was declined | +| ↳ `createdOn` | string | Creation timestamp | +| ↳ `updatedOn` | string | Update timestamp | +| ↳ `reviewers` | array | Explicit reviewers | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `participants` | array | Pull request participants | +| ↳ `type` | string | Bitbucket participant object type | +| ↳ `user` | object | Participating account | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `role` | string | Participant role | +| ↳ `approved` | boolean | Whether the participant approved | +| ↳ `state` | string | Review state | +| ↳ `participatedOn` | string | Timestamp of the participant action | +| ↳ `selfUrl` | string | Pull request API URL | +| ↳ `htmlUrl` | string | Pull request web URL | + +### Bitbucket Decline Pull Request + +Decline an open pull request + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `prId` | number | Yes | Repository-scoped pull request ID | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `pullRequest` | object | Declined pull request | +| ↳ `type` | string | Bitbucket pull request object type | +| ↳ `id` | number | Repository-scoped pull request ID | +| ↳ `title` | string | Pull request title | +| ↳ `description` | string | Pull request description | +| ↳ `state` | string | Pull request state | +| ↳ `draft` | boolean | Whether the pull request is a draft | +| ↳ `queued` | boolean | Whether the pull request is queued | +| ↳ `author` | object | Pull request author | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `closedBy` | object | Account that closed the pull request | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `source` | object | Source endpoint | +| ↳ `branchName` | string | Branch name | +| ↳ `commitHash` | string | Commit hash | +| ↳ `repositoryUuid` | string | Repository UUID | +| ↳ `repositoryFullName` | string | Repository full name | +| ↳ `destination` | object | Destination endpoint | +| ↳ `branchName` | string | Branch name | +| ↳ `commitHash` | string | Commit hash | +| ↳ `repositoryUuid` | string | Repository UUID | +| ↳ `repositoryFullName` | string | Repository full name | +| ↳ `mergeCommitHash` | string | Merge commit hash | +| ↳ `commentCount` | number | Comment count | +| ↳ `taskCount` | number | Open task count | +| ↳ `closeSourceBranch` | boolean | Whether merging closes the source branch | +| ↳ `reason` | string | Reason the pull request was declined | +| ↳ `createdOn` | string | Creation timestamp | +| ↳ `updatedOn` | string | Update timestamp | +| ↳ `reviewers` | array | Explicit reviewers | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `participants` | array | Pull request participants | +| ↳ `type` | string | Bitbucket participant object type | +| ↳ `user` | object | Participating account | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `role` | string | Participant role | +| ↳ `approved` | boolean | Whether the participant approved | +| ↳ `state` | string | Review state | +| ↳ `participatedOn` | string | Timestamp of the participant action | +| ↳ `selfUrl` | string | Pull request API URL | +| ↳ `htmlUrl` | string | Pull request web URL | + +### Bitbucket Approve Pull Request + +Approve a pull request as the authenticated account + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `prId` | number | Yes | Repository-scoped pull request ID | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `participant` | object | Approval participant record | +| ↳ `type` | string | Bitbucket participant object type | +| ↳ `user` | object | Participating account | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `role` | string | Participant role | +| ↳ `approved` | boolean | Whether the participant approved | +| ↳ `state` | string | Review state | +| ↳ `participatedOn` | string | Timestamp of the participant action | + +### Bitbucket Request Pull Request Changes + +Request changes on a pull request as the authenticated account + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `prId` | number | Yes | Repository-scoped pull request ID | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `participant` | object | Change-request participant record | +| ↳ `type` | string | Bitbucket participant object type | +| ↳ `user` | object | Participating account | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `role` | string | Participant role | +| ↳ `approved` | boolean | Whether the participant approved | +| ↳ `state` | string | Review state | +| ↳ `participatedOn` | string | Timestamp of the participant action | + +### Bitbucket Get Pull Request Diff + +Read a bounded UTF-8 unified diff for one pull request file + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `prId` | number | Yes | Repository-scoped pull request ID | +| `path` | string | Yes | Repository-relative file path to include in the diff | +| `maxCharacters` | number | No | Maximum diff characters to return \(1-500000\) | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `diff` | string | Bounded unified diff text decoded as UTF-8 | +| `decodingLossy` | boolean | Whether invalid UTF-8 source bytes were replaced while decoding | +| `truncated` | boolean | Whether later diff text was omitted | +| `returnedBytes` | number | Provider bytes read for the returned diff | +| `fullBytes` | number | Full diff byte size when reported | + +### Bitbucket Get Pull Request Diffstat + +List per-file change statistics for a pull request + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `prId` | number | Yes | Repository-scoped pull request ID | +| `nextUrl` | string | No | Opaque next-page URL returned by a previous Bitbucket call | +| `pageLen` | number | No | Results per page \(1-100\) | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `page` | object | Pagination information | +| ↳ `size` | number | Total result count reported by Bitbucket | +| ↳ `page` | number | Current page number | +| ↳ `pageLen` | number | Number of results requested per page | +| ↳ `nextUrl` | string | Validated URL for the next page | +| ↳ `previousUrl` | string | Validated URL for the previous page | +| `items` | array | Per-file diff statistics | +| ↳ `type` | string | Diffstat object type | +| ↳ `status` | string | File change status | +| ↳ `linesAdded` | number | Lines added | +| ↳ `linesRemoved` | number | Lines removed | +| ↳ `oldPath` | string | Old file path | +| ↳ `newPath` | string | New file path | +| ↳ `oldCommitHash` | string | Old file commit hash | +| ↳ `newCommitHash` | string | New file commit hash | + +### Bitbucket List Pull Request Comments + +List global, inline, and reply comments on a pull request + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `prId` | number | Yes | Repository-scoped pull request ID | +| `q` | string | No | Bitbucket comment filtering expression | +| `sort` | string | No | Bitbucket comment sort expression | +| `nextUrl` | string | No | Opaque next-page URL returned by a previous Bitbucket call | +| `pageLen` | number | No | Results per page \(1-100\) | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `page` | object | Pagination information | +| ↳ `size` | number | Total result count reported by Bitbucket | +| ↳ `page` | number | Current page number | +| ↳ `pageLen` | number | Number of results requested per page | +| ↳ `nextUrl` | string | Validated URL for the next page | +| ↳ `previousUrl` | string | Validated URL for the previous page | +| `items` | array | Pull request comments | +| ↳ `type` | string | Bitbucket comment object type | +| ↳ `id` | number | Comment ID | +| ↳ `createdOn` | string | Creation timestamp | +| ↳ `updatedOn` | string | Update timestamp | +| ↳ `content` | string | Raw comment content | +| ↳ `user` | object | Comment author | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `deleted` | boolean | Whether the comment was deleted | +| ↳ `parentId` | number | Parent comment ID | +| ↳ `inline` | object | Inline comment anchor | +| ↳ `path` | string | Anchored file path | +| ↳ `from` | number | Ending line in the old file | +| ↳ `to` | number | Ending line in the new file | +| ↳ `startFrom` | number | Starting line in the old file | +| ↳ `startTo` | number | Starting line in the new file | +| ↳ `pending` | boolean | Whether the comment is pending | +| ↳ `resolution` | object | Comment resolution details | +| ↳ `resolver` | object | Account that resolved the comment | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `resolvedOn` | string | Resolution timestamp | +| ↳ `selfUrl` | string | Comment API URL | +| ↳ `htmlUrl` | string | Comment web URL | + +### Bitbucket Create Pull Request Comment + +Create a global comment or reply on a pull request + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `prId` | number | Yes | Repository-scoped pull request ID | +| `content` | string | Yes | Raw comment content | +| `parentId` | number | No | Parent comment ID when creating a reply | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `comment` | object | Created comment | +| ↳ `type` | string | Bitbucket comment object type | +| ↳ `id` | number | Comment ID | +| ↳ `createdOn` | string | Creation timestamp | +| ↳ `updatedOn` | string | Update timestamp | +| ↳ `content` | string | Raw comment content | +| ↳ `user` | object | Comment author | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `deleted` | boolean | Whether the comment was deleted | +| ↳ `parentId` | number | Parent comment ID | +| ↳ `inline` | object | Inline comment anchor | +| ↳ `path` | string | Anchored file path | +| ↳ `from` | number | Ending line in the old file | +| ↳ `to` | number | Ending line in the new file | +| ↳ `startFrom` | number | Starting line in the old file | +| ↳ `startTo` | number | Starting line in the new file | +| ↳ `pending` | boolean | Whether the comment is pending | +| ↳ `resolution` | object | Comment resolution details | +| ↳ `resolver` | object | Account that resolved the comment | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `resolvedOn` | string | Resolution timestamp | +| ↳ `selfUrl` | string | Comment API URL | +| ↳ `htmlUrl` | string | Comment web URL | + +### Bitbucket List Pull Request Commit Statuses + +List commit statuses associated with a pull request + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `prId` | number | Yes | Repository-scoped pull request ID | +| `q` | string | No | Bitbucket commit status filtering expression | +| `sort` | string | No | Bitbucket commit status sort expression | +| `nextUrl` | string | No | Opaque next-page URL returned by a previous Bitbucket call | +| `pageLen` | number | No | Results per page \(1-100\) | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `page` | object | Pagination information | +| ↳ `size` | number | Total result count reported by Bitbucket | +| ↳ `page` | number | Current page number | +| ↳ `pageLen` | number | Number of results requested per page | +| ↳ `nextUrl` | string | Validated URL for the next page | +| ↳ `previousUrl` | string | Validated URL for the previous page | +| `items` | array | Pull request commit statuses | +| ↳ `type` | string | Bitbucket commit-status object type | +| ↳ `key` | string | Vendor-unique status key | +| ↳ `refName` | string | Reference name at status creation time | +| ↳ `url` | string | External build URL | +| ↳ `state` | string | Commit status state | +| ↳ `name` | string | Build name | +| ↳ `description` | string | Build description | +| ↳ `createdOn` | string | Creation timestamp | +| ↳ `updatedOn` | string | Update timestamp | +| ↳ `selfUrl` | string | Status API URL | +| ↳ `commitUrl` | string | Commit API URL | + +### Bitbucket List Pipelines + +List pipelines for a Bitbucket Cloud repository + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `refType` | string | No | Reference type filter: BRANCH, TAG, or ANNOTATED_TAG | +| `refName` | string | No | Reference name filter | +| `commitHash` | string | No | Full 40-character target commit SHA-1 filter | +| `selectorType` | string | No | Selector type filter: BRANCH, TAG, CUSTOM, PULLREQUESTS, or DEFAULT | +| `selectorPattern` | string | No | Pipeline selector pattern filter | +| `triggerType` | string | No | Trigger filter: PUSH, MANUAL, SCHEDULED, or PARENT_STEP | +| `status` | string | No | Pipeline status filter | +| `sort` | string | No | Bitbucket pipeline sort expression | +| `nextUrl` | string | No | Opaque next-page URL returned by a previous Bitbucket call | +| `pageLen` | number | No | Results per page \(1-100\) | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `page` | object | Pagination information | +| ↳ `size` | number | Total result count reported by Bitbucket | +| ↳ `page` | number | Current page number | +| ↳ `pageLen` | number | Number of results requested per page | +| ↳ `nextUrl` | string | Validated URL for the next page | +| ↳ `previousUrl` | string | Validated URL for the previous page | +| `items` | array | Pipelines | +| ↳ `type` | string | Bitbucket pipeline object type | +| ↳ `uuid` | string | Pipeline UUID | +| ↳ `buildNumber` | number | Pipeline build number | +| ↳ `creator` | object | Pipeline creator | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `repositoryFullName` | string | Repository full name | +| ↳ `target` | object | Pipeline target | +| ↳ `type` | string | Target object type | +| ↳ `refType` | string | Reference type | +| ↳ `refName` | string | Reference name | +| ↳ `commitHash` | string | Target commit hash | +| ↳ `selectorType` | string | Pipeline selector type | +| ↳ `selectorPattern` | string | Pipeline selector pattern | +| ↳ `triggerType` | string | Pipeline trigger object type | +| ↳ `state` | object | Pipeline state | +| ↳ `name` | string | State name | +| ↳ `stage` | string | In-progress stage name | +| ↳ `result` | string | Completed result name | +| ↳ `errorKey` | string | Completed-error key | +| ↳ `errorMessage` | string | Completed-error message | +| ↳ `createdOn` | string | Creation timestamp | +| ↳ `completedOn` | string | Completion timestamp | +| ↳ `buildSecondsUsed` | number | Build seconds used | +| ↳ `selfUrl` | string | Pipeline API URL | +| ↳ `stepsUrl` | string | Pipeline steps API URL | + +### Bitbucket Get Pipeline + +Get a pipeline by UUID + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `pipelineUuid` | string | Yes | Pipeline UUID | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `pipeline` | object | Pipeline details | +| ↳ `type` | string | Bitbucket pipeline object type | +| ↳ `uuid` | string | Pipeline UUID | +| ↳ `buildNumber` | number | Pipeline build number | +| ↳ `creator` | object | Pipeline creator | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `repositoryFullName` | string | Repository full name | +| ↳ `target` | object | Pipeline target | +| ↳ `type` | string | Target object type | +| ↳ `refType` | string | Reference type | +| ↳ `refName` | string | Reference name | +| ↳ `commitHash` | string | Target commit hash | +| ↳ `selectorType` | string | Pipeline selector type | +| ↳ `selectorPattern` | string | Pipeline selector pattern | +| ↳ `triggerType` | string | Pipeline trigger object type | +| ↳ `state` | object | Pipeline state | +| ↳ `name` | string | State name | +| ↳ `stage` | string | In-progress stage name | +| ↳ `result` | string | Completed result name | +| ↳ `errorKey` | string | Completed-error key | +| ↳ `errorMessage` | string | Completed-error message | +| ↳ `createdOn` | string | Creation timestamp | +| ↳ `completedOn` | string | Completion timestamp | +| ↳ `buildSecondsUsed` | number | Build seconds used | +| ↳ `selfUrl` | string | Pipeline API URL | +| ↳ `stepsUrl` | string | Pipeline steps API URL | + +### Bitbucket Trigger Pipeline + +Run the repository pipeline selected by a branch or ref target + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `refType` | string | Yes | Reference type: branch, tag, named_branch, or bookmark | +| `refName` | string | Yes | Reference name | +| `commitHash` | string | No | Full 40-character commit SHA-1 to run in the reference context | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `pipeline` | object | Triggered pipeline | +| ↳ `type` | string | Bitbucket pipeline object type | +| ↳ `uuid` | string | Pipeline UUID | +| ↳ `buildNumber` | number | Pipeline build number | +| ↳ `creator` | object | Pipeline creator | +| ↳ `type` | string | Bitbucket account object type | +| ↳ `uuid` | string | Bitbucket account UUID | +| ↳ `accountId` | string | Atlassian account ID | +| ↳ `displayName` | string | Account display name | +| ↳ `createdOn` | string | Account creation timestamp | +| ↳ `selfUrl` | string | Account API URL | +| ↳ `htmlUrl` | string | Account web URL | +| ↳ `avatarUrl` | string | Account avatar URL | +| ↳ `repositoryFullName` | string | Repository full name | +| ↳ `target` | object | Pipeline target | +| ↳ `type` | string | Target object type | +| ↳ `refType` | string | Reference type | +| ↳ `refName` | string | Reference name | +| ↳ `commitHash` | string | Target commit hash | +| ↳ `selectorType` | string | Pipeline selector type | +| ↳ `selectorPattern` | string | Pipeline selector pattern | +| ↳ `triggerType` | string | Pipeline trigger object type | +| ↳ `state` | object | Pipeline state | +| ↳ `name` | string | State name | +| ↳ `stage` | string | In-progress stage name | +| ↳ `result` | string | Completed result name | +| ↳ `errorKey` | string | Completed-error key | +| ↳ `errorMessage` | string | Completed-error message | +| ↳ `createdOn` | string | Creation timestamp | +| ↳ `completedOn` | string | Completion timestamp | +| ↳ `buildSecondsUsed` | number | Build seconds used | +| ↳ `selfUrl` | string | Pipeline API URL | +| ↳ `stepsUrl` | string | Pipeline steps API URL | + +### Bitbucket Stop Pipeline + +Stop a running pipeline + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `pipelineUuid` | string | Yes | Pipeline UUID | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `stopped` | boolean | Whether the stop request succeeded | + +### Bitbucket List Pipeline Steps + +List the steps in a pipeline + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `pipelineUuid` | string | Yes | Pipeline UUID | +| `nextUrl` | string | No | Opaque next-page URL returned by a previous Bitbucket call | +| `pageLen` | number | No | Results per page \(1-100\) | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `page` | object | Pagination information | +| ↳ `size` | number | Total result count reported by Bitbucket | +| ↳ `page` | number | Current page number | +| ↳ `pageLen` | number | Number of results requested per page | +| ↳ `nextUrl` | string | Validated URL for the next page | +| ↳ `previousUrl` | string | Validated URL for the previous page | +| `items` | array | Pipeline steps | +| ↳ `type` | string | Bitbucket pipeline-step object type | +| ↳ `uuid` | string | Pipeline step UUID | +| ↳ `startedOn` | string | Step start timestamp | +| ↳ `completedOn` | string | Step completion timestamp | +| ↳ `state` | object | Pipeline step state | +| ↳ `name` | string | State name | +| ↳ `result` | string | Completed result name | +| ↳ `errorKey` | string | Completed-error key | +| ↳ `errorMessage` | string | Completed-error message | +| ↳ `imageName` | string | Build container image name | +| ↳ `setupCommands` | array | Setup commands | +| ↳ `name` | string | Command name | +| ↳ `command` | string | Executable command | +| ↳ `scriptCommands` | array | Build script commands | +| ↳ `name` | string | Command name | +| ↳ `command` | string | Executable command | + +### Bitbucket Get Pipeline Step Log + +Read a bounded UTF-8 tail of a pipeline step log + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `workspaceSlug` | string | Yes | Bitbucket workspace slug or UUID | +| `repoSlug` | string | Yes | Bitbucket repository slug or UUID | +| `pipelineUuid` | string | Yes | Pipeline UUID | +| `stepUuid` | string | Yes | Pipeline step UUID | +| `maxCharacters` | number | No | Maximum trailing log characters to return \(1-200000\) | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `log` | string | Bounded trailing UTF-8 log text | +| `truncated` | boolean | Whether earlier log output was omitted | +| `totalBytes` | number | Full log byte size when reported | + + diff --git a/apps/docs/content/docs/en/integrations/cbinsights.mdx b/apps/docs/content/docs/en/integrations/cbinsights.mdx new file mode 100644 index 00000000000..d41c984a1ec --- /dev/null +++ b/apps/docs/content/docs/en/integrations/cbinsights.mdx @@ -0,0 +1,611 @@ +--- +title: CB Insights +description: Research private markets — firmographics, funding, and predictive scores +--- + +import { BlockInfoCard } from "@/components/ui/block-info-card" + + + +{/* MANUAL-CONTENT-START:intro */} +[CB Insights](https://www.cbinsights.com/) is a private-market intelligence platform. Its API v2 exposes both the underlying firmographic and transaction record — companies, investors, funding rounds, cap tables, exits, business relationships, leadership — and the proprietary models CB Insights layers on top of it: the Mosaic Score, Commercial Maturity, and Exit Probability. + +**Why CB Insights?** +- **Predictive, not just descriptive:** Mosaic Score, Commercial Maturity, and Exit Probability are scored models with published methodologies, and each returns the signals behind it rather than a bare number. +- **Peer-relative by default:** Exit probabilities come with the mean for comparable companies and a ratio to it, so a score can be read against its cohort instead of in isolation. +- **Depth on terms:** Cap table history carries issuance and conversion prices, liquidation preference, participation rights, and anti-dilution provisions — detail that rarely survives into aggregated datasets. +- **Free identity resolution:** The organization lookup never charges credits, so your own records can be matched to CB Insights IDs before you spend anything. + +**Using CB Insights in Sim** + +This integration covers every non-streaming v2 endpoint. Authentication is a client-credential exchange — Sim trades your client ID and secret for a short-lived bearer token on your behalf and refreshes it automatically, so there is no token to manage in the workflow. + +**Key benefits of using CB Insights in Sim:** +- **Credit-aware enrichment:** Resolve companies with the free **Look Up Organizations** operation first, confirm the match, then spend credits only on the records you actually want. +- **Bulk over per-record:** The `List` operations cover up to 100 organizations in a single call — use them instead of looping the single-organization equivalents when refreshing a table. +- **Score history, not just a snapshot:** Mosaic, Commercial Maturity, and Exit Probability each have a history operation, so a trend can be read rather than a point value. +- **Relationship mapping:** **Get Strategy Map** returns the companies connected to an organization grouped by category, with the partnerships, investments, and acquisitions that link them. +- **AI on tap:** **Get Scouting Report** writes a full company analysis, **Ask ChatCBI** answers questions with sources, and **Retrieve Context** returns the raw structured records for your own model to reason over. + +**Before you start** + +Client credentials come from your CB Insights Customer Success Manager rather than a self-serve settings page. **Most operations consume credits, and which datasets answer at all depends on your license** — Firmographics, Financial Transactions, Business Relationships, Management and Board, Outlook, and Scouting Reports are separately licensed. An operation outside your entitlement returns an error from CB Insights rather than partial data. + +Two behaviors are worth knowing before you build against them. A **pending or rumored funding round zeroes the exit probabilities** rather than omitting them, so a `0` alongside a set `incompleteRoundType` means "suppressed", not "unlikely". And on every multi-organization operation, **an organization with no data is omitted from the response** rather than returned empty — treat a missing ID as "no data", not as a failure. + +The two streaming endpoints (`chatcbichunked` and `scoutingreportstream`) are intentionally not exposed; they deliver incremental JSON chunks, and the non-streaming operations here return the same content in one piece. Note that a Scouting Report can take several minutes to generate. +{/* MANUAL-CONTENT-END */} + + +## Usage Instructions + +Integrates the CB Insights API v2 into the workflow. Resolve companies to CB Insights IDs for free, search firmographics across markets and geographies, pull funding rounds, cap tables, investments, and exits, map business relationships, read leadership and board history, and retrieve the proprietary Mosaic Score, Commercial Maturity, and Exit Probability outlooks. Generate AI Scouting Reports, or ask ChatCBI directly. Which datasets answer depends on your CB Insights license. + + + +## Actions + +### CB Insights Look Up Organizations + +Resolve company names or websites to CB Insights organization IDs. This endpoint never charges credits, so use it to match your own records before spending credits on the data endpoints. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `names` | json | No | Organization names to look up, e.g. \["CB Insights"\] | +| `urls` | json | No | Organization websites to look up, e.g. \["cbinsights.com"\] | +| `profileUrl` | string | No | A CB Insights profile URL to resolve. Mutually exclusive with names and urls — the API rejects a request that sets both. | +| `limit` | number | No | Rows to return in a single response, 1-100 | +| `nextPageToken` | string | No | Continuation token from a previous response; omit for the first page | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `orgs` | json | Matched organizations as \[\{orgId, name, description, aliases, urls\}\] | +| `nextPageToken` | string | Token for the next page, or null when there are no more results | +| `totalHits` | number | Total number of matching records | +| `totalHitsRelation` | string | Whether totalHits is exact \('eq'\) or a floor \('gte', used above 10,000\) | + +### CB Insights Search Firmographics + +Search profiles of private companies, public companies, and investors by market, industry, geography, headcount, funding, and valuation. Each field is ANDed together; values within a field are ORed. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `keyword` | string | No | Search term matched against organization names, descriptions, and aliases | +| `orgIds` | json | No | CB Insights organization IDs to return, e.g. \[129410, 129411\] | +| `orgNames` | json | No | Organization names to match exactly, e.g. \["CB Insights"\] | +| `urls` | json | No | Organization websites to match, e.g. \["cbinsights.com"\] | +| `tickers` | json | No | Stock tickers to match, each optionally suffixed with an exchange code after a colon | +| `marketIds` | json | No | CB Insights market IDs to match, e.g. \[6, 95, 106\] | +| `marketNames` | json | No | CB Insights market names to match. Partial matches count — "AI" returns every market whose name contains it. | +| `industryIds` | json | No | CB Insights industry IDs to match \(mid level of the taxonomy\) | +| `sectorIds` | json | No | CB Insights sector IDs to match \(top level of the taxonomy\) | +| `subindustryIds` | json | No | CB Insights sub-industry IDs to match \(lowest level of the taxonomy\) | +| `businessModelIds` | json | No | CB Insights business model IDs to match | +| `technologyIds` | json | No | CB Insights technology landscape IDs to match | +| `collectionIds` | json | No | Expert Collection IDs to search within | +| `countryIds` | json | No | CB Insights country IDs to match | +| `stateProvinceIds` | json | No | CB Insights state or province IDs to match | +| `cityIds` | json | No | CB Insights city IDs to match | +| `continentIds` | json | No | CB Insights continent IDs to match | +| `regionIds` | json | No | CB Insights region IDs to match | +| `orgStatusIds` | json | No | CB Insights organization status IDs to match \(active, acquired, dead, IPO, merged\) | +| `investorOrgIds` | json | No | Return organizations these investor organization IDs have invested in | +| `investorTypeIds` | json | No | Return investor organizations of these investor types | +| `fundingInvestorTypeIds` | json | No | Return organizations funded by these investor types | +| `lastFundingRoundIds` | json | No | CB Insights funding round IDs of the most recent round | +| `lastFundingRoundCategoryIds` | json | No | CB Insights funding round category IDs of the most recent round | +| `minCurrentHeadcount` | number | No | Minimum current headcount | +| `maxCurrentHeadcount` | number | No | Maximum current headcount | +| `minTotalFundingInMillions` | number | No | Minimum total funding raised, in millions of US dollars | +| `maxTotalFundingInMillions` | number | No | Maximum total funding raised, in millions of US dollars | +| `minValuationInMillions` | number | No | Minimum valuation, in millions of US dollars | +| `maxValuationInMillions` | number | No | Maximum valuation, in millions of US dollars | +| `minLastFundingDate` | string | No | Earliest date of the most recent funding round, as YYYY-MM-DD | +| `maxLastFundingDate` | string | No | Latest date of the most recent funding round, as YYYY-MM-DD | +| `vcBacked` | boolean | No | Restrict to organizations that have received venture funding | +| `sortField` | string | No | Sort field: orgName, orgId, lastUpdateTime, lastFundingDate, latestValuation, mosaicOverall, mosaicManagement, mosaicMarket, mosaicMomentum, mosaicMoney, headcountCurrent, headcount6MonthGrowth, headcount12MonthGrowth, or headcount24MonthGrowth | +| `sortDirection` | string | No | Sort direction, "asc" or "desc" | +| `limit` | number | No | Rows to return in a single response, 1-100 | +| `nextPageToken` | string | No | Continuation token from a previous response; omit for the first page | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `orgs` | json | Matching profiles as \[\{orgId, summary, taxonomy, financials, headcount, identifiers, businessModels, competitors, expertCollections, parentOrgs, childOrgs\}\] | +| `nextPageToken` | string | Token for the next page, or null when there are no more results | +| `totalHits` | number | Total number of matching records | +| `totalHitsRelation` | string | Whether totalHits is exact \('eq'\) or a floor \('gte', used above 10,000\) | + +### CB Insights Get Organization Fundings + +Retrieve the funding rounds one organization has received, its cap table history, and AI-generated insights extracting the key themes of each deal. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgId` | number | Yes | CB Insights organization ID. Resolve a name or website to one with Look Up Organizations, which never charges credits. | +| `limit` | number | No | Rows to return in a single response, 1-100 | +| `nextPageToken` | string | No | Continuation token from a previous response; omit for the first page | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `fundings` | json | Rounds as \[\{dealId, date, round, roundCategory, amountInMillions, valuationInMillions, investors, insights, sources\}\] | +| `capTableHistory` | json | Ownership structure as \[\{dealId, roundType, issuancePrice, conversionPrice, percentageOwned, sharesAuthorized, terms\}\] | +| `nextPageToken` | string | Token for the next page, or null when there are no more results | +| `totalHits` | number | Total number of matching records | +| `totalHitsRelation` | string | Whether totalHits is exact \('eq'\) or a floor \('gte', used above 10,000\) | + +### CB Insights Get Organization Investments + +Retrieve the rounds in which one organization invested in another, with AI-generated insights extracting the key themes of each deal. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgId` | number | Yes | CB Insights organization ID. Resolve a name or website to one with Look Up Organizations, which never charges credits. | +| `limit` | number | No | Rows to return in a single response, 1-100 | +| `nextPageToken` | string | No | Continuation token from a previous response; omit for the first page | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `investments` | json | Rounds as \[\{dealId, date, round, roundCategory, amountInMillions, valuationInMillions, recipient, investors, insights, sources\}\] | +| `nextPageToken` | string | Token for the next page, or null when there are no more results | +| `totalHits` | number | Total number of matching records | +| `totalHitsRelation` | string | Whether totalHits is exact \('eq'\) or a floor \('gte', used above 10,000\) | + +### CB Insights Get Organization Portfolio Exits + +Retrieve exit rounds for companies this organization invested in before the exit, with AI-generated insights on each deal. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgId` | number | Yes | CB Insights organization ID. Resolve a name or website to one with Look Up Organizations, which never charges credits. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `portfolioExits` | json | Exits as \[\{dealId, date, round, roundCategory, amountInMillions, valuationInMillions, recipient, investors, insights, sources\}\] | + +### CB Insights Get Organization Business Relationships + +Retrieve one organization's partnerships, client/vendor relationships, and licensing activity, with AI-generated insights on each. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgId` | number | Yes | CB Insights organization ID. Resolve a name or website to one with Look Up Organizations, which never charges credits. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `businessRelationships` | json | Relationships as \[\{relationshipId, startDate, partners, insights, newsSnippet, sources, lastUpdateTime\}\] | + +### CB Insights Get Organization Management and Board + +Retrieve an organization's leadership team and board members with their education, work history, and board seats, plus the Management factor of its Mosaic Score. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgId` | number | Yes | CB Insights organization ID. Resolve a name or website to one with Look Up Organizations, which never charges credits. | +| `titleIds` | json | No | CB Insights person title IDs to filter the people returned, e.g. \[50, 75\] | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `people` | json | People as \[\{personId, givenName, middleName, surname, email, linkedInUrl, education, workExperience, boardAssociations\}\] | +| `mosaicManagement` | number | Management factor of the Mosaic Score, measuring the pedigree and track record of the leadership team | + +### CB Insights Get Organization Outlook + +Retrieve an organization's current Mosaic Score, Commercial Maturity level, and two-year IPO and M&A exit probabilities, with the signals driving each. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgId` | number | Yes | CB Insights organization ID. Resolve a name or website to one with Look Up Organizations, which never charges credits. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `mosaicScore` | json | Mosaic Score on a 0-1000 scale: \{overall, management, market, momentum, money\}, each with scoreValue, asOfDate, and scoreInsights | +| `commercialMaturity` | json | Commercial Maturity on a 1-5 scale: \{maturityLevel: \{level, stage, stageDescription, asOfDate\}, commercialMaturitySignals\}. Available only for a subset of companies. | +| `exitProbability` | json | Two-year exit probability: \{ipo, mna, exitSignals, incompleteRoundType\}. A pending round zeroes the probabilities rather than omitting them. | + +### CB Insights Get Organization Funding Window + +Retrieve the estimated window in which an organization is likely to raise its next round, with the cohort it was compared against. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgId` | number | Yes | CB Insights organization ID. Resolve a name or website to one with Look Up Organizations, which never charges credits. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `windowStart` | string | Estimated start of the next funding window, as YYYY-MM-DD | +| `windowEnd` | string | Estimated end of the next funding window, as YYYY-MM-DD | +| `cohortNextRoundRate` | number | Share of the cohort that historically raised another round, as a decimal between 0 and 1 | +| `cohortCriteria` | json | How the comparison cohort was defined: \{cohortGeo, cohortRoundCategory, cohortLandscapes\} | +| `latestFunding` | json | The latest equity-backed round: \{date, dealId\} | + +### CB Insights Get Organization Revenue + +Retrieve reported and estimated revenue by calendar year for one organization, with the sources behind each figure. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgId` | number | Yes | CB Insights organization ID. Resolve a name or website to one with Look Up Organizations, which never charges credits. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `orgId` | number | CB Insights organization ID | +| `orgName` | string | The organization's name | +| `orgUrl` | string | The organization's website | +| `revenue` | json | Revenue by year as \[\{calendarYear, lowestValue, averageValue, highestValue, isActual, reportedMetric, yoyGrowthPercent, sources\}\] | + +### CB Insights Get Mosaic History + +Retrieve an organization's historical Mosaic Scores — overall plus the management, market, momentum, and money factors — so a trend can be read rather than a single snapshot. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgId` | number | Yes | CB Insights organization ID. Resolve a name or website to one with Look Up Organizations, which never charges credits. | +| `startDate` | string | No | Earliest date to return, as YYYY-MM-DD. Must be on or after 2024-01-01 and within the last 24 months. Defaults to the later of one year ago and 2024-01-01. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `overall` | json | Overall Mosaic Score over time as \[\{asOfDate, scoreValue\}\] | +| `management` | json | Management factor over time as \[\{asOfDate, scoreValue\}\] | +| `market` | json | Market factor over time as \[\{asOfDate, scoreValue\}\] | +| `momentum` | json | Momentum factor over time as \[\{asOfDate, scoreValue\}\] | +| `money` | json | Money factor over time as \[\{asOfDate, scoreValue\}\] | + +### CB Insights Get Commercial Maturity History + +Retrieve an organization's historical Commercial Maturity levels, tracking how its ability to compete for customers or serve as a partner has moved over time. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgId` | number | Yes | CB Insights organization ID. Resolve a name or website to one with Look Up Organizations, which never charges credits. | +| `startDate` | string | No | Earliest date to return, as YYYY-MM-DD. Must be on or after 2024-07-25 and within 24 months of endDate. Defaults to the later of one year ago and 2024-07-25. | +| `endDate` | string | No | Latest date to return, as YYYY-MM-DD. Must be on or after 2024-07-25 and within 24 months of startDate. Defaults to today. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `commercialMaturityHistory` | json | Maturity levels over time as \[\{asOfDate, level, stage, stageDescription\}\], where level runs 1-5 | + +### CB Insights Get Exit Probability History + +Retrieve an organization's historical two-year IPO and M&A exit probabilities, each alongside the mean for comparable companies. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgId` | number | Yes | CB Insights organization ID. Resolve a name or website to one with Look Up Organizations, which never charges credits. | +| `startDate` | string | No | Earliest date to return, as YYYY-MM-DD. Must be on or after 2025-02-25 and within 24 months of endDate. Defaults to the later of one year ago and 2025-02-25. | +| `endDate` | string | No | Latest date to return, as YYYY-MM-DD. Must be on or after 2025-02-25 and within 24 months of startDate. Defaults to today. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `ipo` | json | IPO probability over time as \[\{asOfDate, exitProbability, meanProbability, ratioToMean\}\] | +| `mna` | json | M&A probability over time as \[\{asOfDate, exitProbability, meanProbability, ratioToMean\}\] | +| `incompleteRoundType` | string | An in-progress round, if any. A pending round zeroes every probability; a rumored round zeroes only the matching exit type. | + +### CB Insights Get Strategy Map + +Retrieve the companies related to an organization, grouped into industry categories, with the relationships, investments, and acquisitions that connect them. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgId` | number | Yes | CB Insights organization ID. Resolve a name or website to one with Look Up Organizations, which never charges credits. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `orgName` | string | The organization's name | +| `logoUrl` | string | URL of the organization's logo | +| `categories` | json | Industry categories as \[\{name, companies: \[\{orgId, name, logoUrl, connections: \{businessRelationships, investments, acquisitions\}\}\]\}\] | + +### CB Insights Get Scouting Report + +Generate an AI-written Scouting Report on a private company covering its business model, market position, strengths, and opportunities. Only active companies are eligible, and generation can take several minutes. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgId` | number | Yes | CB Insights organization ID of an active company. Resolve a name or website to one with Look Up Organizations, which never charges credits. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `orgInfo` | json | Firmographics and proprietary scores for the company: \{id, name, url, description, foundedYear, headcount, address, stage, totalFunding, lastFundingDate, overallMosaicScore, commercialMaturity\} | +| `reportMarkdown` | string | The Scouting Report as Markdown, including citations | +| `reportJson` | string | The Scouting Report as a JSON string. Citation links are not included in this form — use reportMarkdown when they matter. | + +### CB Insights List Fundings + +Retrieve funding rounds and cap table history for up to 100 organizations at once, with AI-generated insights extracting the key themes of each deal. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgIds` | json | Yes | CB Insights organization IDs, 1-100 per request, e.g. \[129410, 1034157\] | +| `limit` | number | No | Rows to return in a single response, 1-100 | +| `nextPageToken` | string | No | Continuation token from a previous response; omit for the first page | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `orgs` | json | Organizations as \[\{orgId, fundings, capTableHistory\}\]. An organization with no data is omitted from the response. | +| `nextPageToken` | string | Token for the next page, or null when there are no more results | +| `totalHits` | number | Total number of matching records | +| `totalHitsRelation` | string | Whether totalHits is exact \('eq'\) or a floor \('gte', used above 10,000\) | + +### CB Insights List Investments + +Retrieve the rounds up to 100 organizations participated in as investors, with AI-generated insights extracting the key themes of each deal. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgIds` | json | Yes | CB Insights organization IDs, 1-100 per request, e.g. \[129410, 1034157\] | +| `limit` | number | No | Rows to return in a single response, 1-100 | +| `nextPageToken` | string | No | Continuation token from a previous response; omit for the first page | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `orgs` | json | Organizations as \[\{orgId, investments\}\]. An organization with no data is omitted from the response. | +| `nextPageToken` | string | Token for the next page, or null when there are no more results | +| `totalHits` | number | Total number of matching records | +| `totalHitsRelation` | string | Whether totalHits is exact \('eq'\) or a floor \('gte', used above 10,000\) | + +### CB Insights List Portfolio Exits + +Retrieve exit rounds for companies up to 100 organizations invested in before the exit, with AI-generated insights on each deal. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgIds` | json | Yes | CB Insights organization IDs, 1-100 per request, e.g. \[129410, 1034157\] | +| `limit` | number | No | Rows to return in a single response, 1-100 | +| `nextPageToken` | string | No | Continuation token from a previous response; omit for the first page | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `orgs` | json | Organizations as \[\{orgId, portfolioExits\}\]. An organization with no data is omitted from the response. | +| `nextPageToken` | string | Token for the next page, or null when there are no more results | +| `totalHits` | number | Total number of matching records | +| `totalHitsRelation` | string | Whether totalHits is exact \('eq'\) or a floor \('gte', used above 10,000\) | + +### CB Insights List Business Relationships + +Retrieve partnerships, client/vendor relationships, and licensing activity for up to 100 organizations at once, with AI-generated insights on each. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgIds` | json | Yes | CB Insights organization IDs, 1-100 per request, e.g. \[129410, 1034157\] | +| `nextPageToken` | string | No | Continuation token from a previous response; omit for the first page | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `orgs` | json | Organizations as \[\{orgId, businessRelationships\}\] | +| `nextPageToken` | string | Token for the next page, or null when there are no more results | +| `totalHits` | number | Total number of matching records | +| `totalHitsRelation` | string | Whether totalHits is exact \('eq'\) or a floor \('gte', used above 10,000\) | + +### CB Insights List Management and Board + +Retrieve leadership teams, board members, and the Management factor of the Mosaic Score for up to 100 organizations at once. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgIds` | json | Yes | CB Insights organization IDs, 1-100 per request, e.g. \[129410, 1034157\] | +| `titleIds` | json | No | CB Insights person title IDs to filter the people returned, e.g. \[50, 75\] | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `orgs` | json | Organizations as \[\{orgId, managementAndBoard: \{mosaicManagement, people\}\}\]. An organization with no data is omitted from the response. | + +### CB Insights List Outlook + +Retrieve Mosaic Score, Commercial Maturity, and Exit Probability for up to 100 organizations at once. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgIds` | json | Yes | CB Insights organization IDs, 1-100 per request, e.g. \[129410, 1034157\] | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `orgs` | json | Organizations as \[\{orgId, mosaicScore, commercialMaturity, exitProbability\}\]. An organization with no data is omitted from the response. | + +### CB Insights List Funding Windows + +Retrieve the estimated next-round funding window for up to 100 organizations at once, with the cohort each was compared against. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgIds` | json | Yes | CB Insights organization IDs, 1-100 per request, e.g. \[129410, 1034157\] | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `orgs` | json | Organizations as \[\{orgId, windowStart, windowEnd, cohortNextRoundRate, cohortCriteria, latestFunding\}\]. An organization with no data is omitted from the response. | + +### CB Insights List Revenue + +Retrieve reported and estimated revenue by calendar year for up to 100 organizations at once. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `orgIds` | json | Yes | CB Insights organization IDs, 1-100 per request, e.g. \[129410, 1034157\] | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `orgs` | json | Organizations as \[\{orgId, orgName, orgUrl, revenue\}\]. An organization with no data is omitted from the response. | + +### CB Insights Chat + +Ask ChatCBI a question in natural language and get an answer grounded in CB Insights data, with its sources and suggested follow-ups. Uses generative AI and can be wrong — verify anything that matters. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `message` | string | Yes | The question to ask, e.g. "Which emerging technology markets are seeing the highest equity funding growth right now?" | +| `chatId` | string | No | Conversation ID returned by a previous call. Pass it to continue that conversation rather than starting a new one. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `chatId` | string | Conversation ID. Pass it back as chatId to continue this conversation. | +| `title` | string | Title CB Insights gave the conversation | +| `message` | string | ChatCBI's answer, as Markdown | +| `sources` | json | Sources behind the answer as \[\{sourceIndex, result: \{title, url, date, thumbnailUrl\}\}\] | +| `relatedContent` | json | Related references as \[\{title, url, date, thumbnailUrl\}\] | +| `suggestions` | json | Suggested follow-up questions | + +### CB Insights Retrieve Context + +Retrieve the raw structured CB Insights data relevant to a question, for feeding your own model rather than reading a written answer. Uses generative AI and can be wrong — verify anything that matters. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `clientId` | string | Yes | CB Insights API client ID, exchanged for a bearer token before each call | +| `clientSecret` | string | Yes | CB Insights API client secret, exchanged for a bearer token before each call | +| `message` | string | Yes | The question to retrieve context for. Must be under 10,000 characters. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `data` | string | Retrieved records as a JSON string, keyed by source \(companySearch, dealSearch, markets, scoutingReports, businessRelationships, revenue, investments, and others\) | +| `guidance` | json | Notes describing what each returned data source contains | + + diff --git a/apps/docs/content/docs/en/integrations/crunchbase.mdx b/apps/docs/content/docs/en/integrations/crunchbase.mdx new file mode 100644 index 00000000000..15727a51b46 --- /dev/null +++ b/apps/docs/content/docs/en/integrations/crunchbase.mdx @@ -0,0 +1,369 @@ +--- +title: Crunchbase +description: Search and look up companies, people, funding rounds, and acquisitions +--- + +import { BlockInfoCard } from "@/components/ui/block-info-card" + + + +{/* MANUAL-CONTENT-START:intro */} +[Crunchbase](https://www.crunchbase.com/) is the private-market data platform companies use to find, research, and track businesses. Its Data API exposes the same graph the site is built on — organizations, people, funding rounds, acquisitions, IPOs, investments, jobs, events, and the relationships between them — through a single, uniform REST interface. + +**Why Crunchbase?** +- **One graph, not a scrape:** Companies, founders, investors, rounds, and deals are linked entities with stable UUIDs and permalinks, so a lookup resolves to the same record every time. +- **Predicate search:** Every collection is queryable with the same filter grammar — twenty operators over any field the collection publishes — so an ideal-customer profile becomes a query rather than a script. +- **Keyset pagination:** Results page forward by cursor instead of offset, so a full result set can be walked without the deep-page cost. +- **Deletion feed:** A dedicated endpoint reports what Crunchbase removed, so a mirrored copy can be pruned in step with the source rather than drifting. + +**Using Crunchbase in Sim** + +Sim's Crunchbase integration covers the Data API end to end with an API key. Four collections most workflows reach for — organizations, people, funding rounds, and acquisitions — get dedicated search and lookup operations with sensible default field sets. The generic **Search Any Collection** and **Get Any Entity** operations reach the remaining 39 collections, including funds, investments, IPOs, jobs, press references, layoffs, insights, and predictions. + +**Key benefits of using Crunchbase in Sim:** +- **Account enrichment:** Resolve a company name to its permalink with Autocomplete, then pull headcount, headquarters, categories, and founding date onto the record. +- **Target list building:** Turn an ICP into search predicates, page the full result set with the returned cursor, and write the companies to a table. +- **Funding and deal monitoring:** Watch rounds and acquisitions announced in a window and route the summary to Slack, email, or a table. +- **Deep relationship traversal:** **Get Entity Card** pages a single related-entity card — an investor's portfolio, a company's founders, a round's investors — past the 100-item cap an inline card request stops at. +- **Field discovery:** **Get Fields Metadata** lists exactly which fields each collection publishes, which is how a query gets grounded before it runs. + +**Before you start** + +Requests authenticate with the `X-cb-user-key` header, and the API is rate limited to 200 calls per minute. Crunchbase sells the API in packages — Firmographic, Core Financials, Advanced Financials, Insights Only, and Predictions & Insights — and **which collections and fields answer depends on the package your key is licensed for**. The default field sets in this integration are drawn from the narrowest package that publishes each collection, so they resolve on the widest range of licenses; a request for a collection or field outside your license returns an error from Crunchbase rather than partial data. +{/* MANUAL-CONTENT-END */} + + +## Usage Instructions + +Integrates the Crunchbase Data API into the workflow. Search organizations, people, funding rounds, and acquisitions with filter predicates, reach the other 39 collections through the generic search and lookup operations, page a single related-entity card past its 100-item cap, autocomplete names into identifiers, follow the deleted-entity feed, and list the fields each collection publishes. Which collections and fields resolve depends on your Crunchbase license. + + + +## Actions + +### Crunchbase Search Organizations + +Search Crunchbase companies, investors, and schools with filter predicates on funding, headcount, location, category, and rank. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Crunchbase API key, sent as the X-cb-user-key header | +| `query` | json | Yes | Filter predicates, combined with AND. Array of \{type:"predicate", field_id, operator_id, values\}. Operators: blank, eq, not_eq, gt, gte, lt, lte, starts, contains, not_contains, between, includes, not_includes, includes_all, not_includes_all, domain_eq, not_domain_eq, domain_blank, domain_includes, not_domain_includes. Max 25 predicates. Example: \[\{"type":"predicate","field_id":"categories","operator_id":"includes","values":\["biotechnology"\]\}\] | +| `fieldIds` | json | No | Organization fields to return as columns, e.g. \["identifier","name","founded_on","categories"\]. Defaults to identifier, name, short_description, website_url, linkedin, location_identifiers, categories, founded_on, num_employees_enum, operating_status, rank_org, permalink. | +| `order` | json | No | Sort clauses, e.g. \[\{"field_id":"rank_org","sort":"asc","nulls":"last"\}\]. Sort is "asc" or "desc". | +| `limit` | number | No | Rows to return, 1-1000 \(default 100\) | +| `afterId` | string | No | UUID of the last entity on the current page, to fetch the next page. Cannot be combined with beforeId. | +| `beforeId` | string | No | UUID of the first entity on the current page, to fetch the previous page. Cannot be combined with afterId. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `count` | number | Total number of organizations matching the query | +| `entities` | json | Matching organizations as \[\{uuid, properties\}\], where properties holds the requested field_ids | +| `nextAfterId` | string | UUID of the last row, to pass as afterId for the next page | + +### Crunchbase Get Organization + +Look up a single Crunchbase organization by permalink or UUID, returning the requested fields and related cards. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Crunchbase API key, sent as the X-cb-user-key header | +| `entityId` | string | Yes | Organization permalink \(e.g. "tesla-motors"\) or UUID | +| `fieldIds` | json | No | Organization fields to return, e.g. \["identifier","name","founded_on","categories"\]. Defaults to identifier, name, short_description, website_url, linkedin, location_identifiers, categories, founded_on, num_employees_enum, operating_status, rank_org, permalink. | +| `cardIds` | json | No | Related-entity cards to include, e.g. \["founders","headquarters_address"\]. Available on every license tier: child_organizations, child_ownerships, event_appearances, fields, founders, headquarters_address, parent_organization, parent_ownership. A card returns at most 100 items. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `uuid` | string | Crunchbase UUID of the organization | +| `name` | string | Organization name | +| `permalink` | string | Crunchbase permalink of the organization | +| `properties` | json | Requested organization fields, keyed by field_id | +| `cards` | json | Requested related-entity cards, keyed by card_id | + +### Crunchbase Search People + +Search Crunchbase people — founders, executives, and investors — with filter predicates on job title, organization, location, and rank. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Crunchbase API key, sent as the X-cb-user-key header | +| `query` | json | Yes | Filter predicates, combined with AND. Array of \{type:"predicate", field_id, operator_id, values\}. Operators: blank, eq, not_eq, gt, gte, lt, lte, starts, contains, not_contains, between, includes, not_includes, includes_all, not_includes_all, domain_eq, not_domain_eq, domain_blank, domain_includes, not_domain_includes. Max 25 predicates. Example: \[\{"type":"predicate","field_id":"primary_job_title","operator_id":"contains","values":\["Founder"\]\}\] | +| `fieldIds` | json | No | Person fields to return as columns, e.g. \["identifier","name","primary_job_title","primary_organization"\]. Defaults to identifier, name, first_name, last_name, primary_job_title, primary_organization, short_description, location_identifiers, linkedin, rank_person, permalink. | +| `order` | json | No | Sort clauses, e.g. \[\{"field_id":"rank_person","sort":"asc","nulls":"last"\}\]. Sort is "asc" or "desc". | +| `limit` | number | No | Rows to return, 1-1000 \(default 100\) | +| `afterId` | string | No | UUID of the last entity on the current page, to fetch the next page. Cannot be combined with beforeId. | +| `beforeId` | string | No | UUID of the first entity on the current page, to fetch the previous page. Cannot be combined with afterId. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `count` | number | Total number of people matching the query | +| `entities` | json | Matching people as \[\{uuid, properties\}\], where properties holds the requested field_ids | +| `nextAfterId` | string | UUID of the last row, to pass as afterId for the next page | + +### Crunchbase Get Person + +Look up a single Crunchbase person by permalink or UUID, returning the requested fields and related cards. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Crunchbase API key, sent as the X-cb-user-key header | +| `entityId` | string | Yes | Person permalink \(e.g. "elon-musk"\) or UUID | +| `fieldIds` | json | No | Person fields to return, e.g. \["identifier","name","primary_job_title","primary_organization"\]. Defaults to identifier, name, first_name, last_name, primary_job_title, primary_organization, short_description, location_identifiers, linkedin, rank_person, permalink. | +| `cardIds` | json | No | Related-entity cards to include, e.g. \["jobs","primary_organization"\]. Available: degrees, event_appearances, fields, founded_organizations, jobs, primary_job, primary_organization. A card returns at most 100 items. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `uuid` | string | Crunchbase UUID of the person | +| `name` | string | Full name of the person | +| `permalink` | string | Crunchbase permalink of the person | +| `properties` | json | Requested person fields, keyed by field_id | +| `cards` | json | Requested related-entity cards, keyed by card_id | + +### Crunchbase Search Funding Rounds + +Search Crunchbase funding rounds with filter predicates on announced date, investment type, amount raised, and investors. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Crunchbase API key, sent as the X-cb-user-key header | +| `query` | json | Yes | Filter predicates, combined with AND. Array of \{type:"predicate", field_id, operator_id, values\}. Operators: blank, eq, not_eq, gt, gte, lt, lte, starts, contains, not_contains, between, includes, not_includes, includes_all, not_includes_all, domain_eq, not_domain_eq, domain_blank, domain_includes, not_domain_includes. Max 25 predicates. Example: \[\{"type":"predicate","field_id":"announced_on","operator_id":"gte","values":\["2026-01-01"\]\}\] | +| `fieldIds` | json | No | Funding round fields to return as columns, e.g. \["identifier","announced_on","money_raised","investor_identifiers"\]. Defaults to identifier, announced_on, investment_type, investment_stage, money_raised, funded_organization_identifier, investor_identifiers, lead_investor_identifiers, num_investors, short_description, permalink. | +| `order` | json | No | Sort clauses, e.g. \[\{"field_id":"announced_on","sort":"desc","nulls":"last"\}\]. Sort is "asc" or "desc". | +| `limit` | number | No | Rows to return, 1-1000 \(default 100\) | +| `afterId` | string | No | UUID of the last entity on the current page, to fetch the next page. Cannot be combined with beforeId. | +| `beforeId` | string | No | UUID of the first entity on the current page, to fetch the previous page. Cannot be combined with afterId. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `count` | number | Total number of funding rounds matching the query | +| `entities` | json | Matching funding rounds as \[\{uuid, properties\}\], where properties holds the requested field_ids | +| `nextAfterId` | string | UUID of the last row, to pass as afterId for the next page | + +### Crunchbase Get Funding Round + +Look up a single Crunchbase funding round by permalink or UUID, returning the requested fields and related cards. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Crunchbase API key, sent as the X-cb-user-key header | +| `entityId` | string | Yes | Funding round permalink \(e.g. "tesla-motors-series-c--12345678"\) or UUID | +| `fieldIds` | json | No | Funding round fields to return, e.g. \["identifier","announced_on","money_raised","investor_identifiers"\]. Defaults to identifier, announced_on, investment_type, investment_stage, money_raised, funded_organization_identifier, investor_identifiers, lead_investor_identifiers, num_investors, short_description, permalink. | +| `cardIds` | json | No | Related-entity cards to include, e.g. \["investors","organization"\]. Available: fields, investments, investors, lead_investors, organization, partners, press_references. A card returns at most 100 items. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `uuid` | string | Crunchbase UUID of the funding round | +| `name` | string | Funding round name | +| `permalink` | string | Crunchbase permalink of the funding round | +| `properties` | json | Requested funding round fields, keyed by field_id | +| `cards` | json | Requested related-entity cards, keyed by card_id | + +### Crunchbase Search Acquisitions + +Search Crunchbase acquisitions with filter predicates on announced date, price, acquisition type, and the companies involved. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Crunchbase API key, sent as the X-cb-user-key header | +| `query` | json | Yes | Filter predicates, combined with AND. Array of \{type:"predicate", field_id, operator_id, values\}. Operators: blank, eq, not_eq, gt, gte, lt, lte, starts, contains, not_contains, between, includes, not_includes, includes_all, not_includes_all, domain_eq, not_domain_eq, domain_blank, domain_includes, not_domain_includes. Max 25 predicates. Example: \[\{"type":"predicate","field_id":"announced_on","operator_id":"gte","values":\["2026-01-01"\]\}\] | +| `fieldIds` | json | No | Acquisition fields to return as columns, e.g. \["identifier","acquiree_identifier","acquirer_identifier","price"\]. Defaults to identifier, acquiree_identifier, acquirer_identifier, announced_on, completed_on, price, acquisition_type, status, terms, short_description, permalink. | +| `order` | json | No | Sort clauses, e.g. \[\{"field_id":"announced_on","sort":"desc","nulls":"last"\}\]. Sort is "asc" or "desc". | +| `limit` | number | No | Rows to return, 1-1000 \(default 100\) | +| `afterId` | string | No | UUID of the last entity on the current page, to fetch the next page. Cannot be combined with beforeId. | +| `beforeId` | string | No | UUID of the first entity on the current page, to fetch the previous page. Cannot be combined with afterId. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `count` | number | Total number of acquisitions matching the query | +| `entities` | json | Matching acquisitions as \[\{uuid, properties\}\], where properties holds the requested field_ids | +| `nextAfterId` | string | UUID of the last row, to pass as afterId for the next page | + +### Crunchbase Get Acquisition + +Look up a single Crunchbase acquisition by permalink or UUID, returning the requested fields and related cards. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Crunchbase API key, sent as the X-cb-user-key header | +| `entityId` | string | Yes | Acquisition permalink or UUID | +| `fieldIds` | json | No | Acquisition fields to return, e.g. \["identifier","acquiree_identifier","acquirer_identifier","price"\]. Defaults to identifier, acquiree_identifier, acquirer_identifier, announced_on, completed_on, price, acquisition_type, status, terms, short_description, permalink. | +| `cardIds` | json | No | Related-entity cards to include, e.g. \["acquiree_organization","acquirer_organization"\]. Available: acquiree_organization, acquirer_organization, fields, press_references. A card returns at most 100 items. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `uuid` | string | Crunchbase UUID of the acquisition | +| `name` | string | Acquisition name | +| `permalink` | string | Crunchbase permalink of the acquisition | +| `properties` | json | Requested acquisition fields, keyed by field_id | +| `cards` | json | Requested related-entity cards, keyed by card_id | + +### Crunchbase Search Entities + +Search any Crunchbase collection — events, jobs, ipos, funds, investments, press references, layoffs, insights, predictions, and more — with filter predicates. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Crunchbase API key, sent as the X-cb-user-key header | +| `collection` | string | Yes | Collection to search. One of: acquisition_predictions, acquisitions, addresses, awards, categories, category_groups, closure_predictions, current_valuation_estimates, degrees, diversity_spotlights, event_appearances, events, funding_predictions, funding_rounds, funds, growth_insights, growth_predictions, investments, investor_insights, investor_matches, ipo_predictions, ipos, jobs, key_employee_changes, layoff_predictions, layoffs, legal_proceedings, locations, market_insight_reasons, market_insights, micro_categories, org_similarities, organizations, ownerships, partnership_announcements, people, press_references, principals, product_launches, product_similarities, products, remain_private_predictions, research_insights. | +| `query` | json | Yes | Filter predicates, combined with AND. Array of \{type:"predicate", field_id, operator_id, values\}. Operators: blank, eq, not_eq, gt, gte, lt, lte, starts, contains, not_contains, between, includes, not_includes, includes_all, not_includes_all, domain_eq, not_domain_eq, domain_blank, domain_includes, not_domain_includes. Max 25 predicates. | +| `fieldIds` | json | Yes | Fields to return as columns for the chosen collection, e.g. \["identifier","short_description"\]. Required — the valid ids differ per collection; list them with the Get Fields Metadata operation. | +| `order` | json | No | Sort clauses, e.g. \[\{"field_id":"updated_at","sort":"desc","nulls":"last"\}\]. Sort is "asc" or "desc". | +| `limit` | number | No | Rows to return, 1-1000 \(default 100\) | +| `afterId` | string | No | UUID of the last entity on the current page, to fetch the next page. Cannot be combined with beforeId. | +| `beforeId` | string | No | UUID of the first entity on the current page, to fetch the previous page. Cannot be combined with afterId. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `count` | number | Total number of entities matching the query | +| `entities` | json | Matching entities as \[\{uuid, properties\}\], where properties holds the requested field_ids | +| `nextAfterId` | string | UUID of the last row, to pass as afterId for the next page | + +### Crunchbase Get Entity + +Look up a single entity in any Crunchbase collection — events, jobs, ipos, funds, investments, press references, insights, predictions, and more — by permalink or UUID. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Crunchbase API key, sent as the X-cb-user-key header | +| `collection` | string | Yes | Collection the entity belongs to. One of: acquisition_predictions, acquisitions, addresses, awards, categories, category_groups, closure_predictions, current_valuation_estimates, degrees, diversity_spotlights, event_appearances, events, funding_predictions, funding_rounds, funds, growth_insights, growth_predictions, investments, investor_insights, investor_matches, ipo_predictions, ipos, jobs, key_employee_changes, layoff_predictions, layoffs, legal_proceedings, locations, market_insight_reasons, market_insights, micro_categories, org_similarities, organizations, ownerships, partnership_announcements, people, press_references, principals, product_launches, product_similarities, products, remain_private_predictions, research_insights. | +| `entityId` | string | Yes | Entity permalink or UUID | +| `fieldIds` | json | No | Fields to return for the chosen collection, e.g. \["identifier","short_description"\]. Leave empty to accept the default projection the API returns; list the valid ids with the Get Fields Metadata operation. | +| `cardIds` | json | No | Related-entity cards to include. The valid ids differ per collection, and a card returns at most 100 items — use the Get Entity Card operation to page past that. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `uuid` | string | Crunchbase UUID of the entity | +| `name` | string | Name of the entity | +| `permalink` | string | Crunchbase permalink of the entity | +| `properties` | json | Requested entity fields, keyed by field_id | +| `cards` | json | Requested related-entity cards, keyed by card_id | + +### Crunchbase Get Entity Card + +Page through one related-entity card of a Crunchbase entity — an investor's investments, a company's founders, a round's investors — past the 100-item cap an inline card request returns. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Crunchbase API key, sent as the X-cb-user-key header | +| `collection` | string | Yes | Collection the entity belongs to. One of: acquisitions, addresses, categories, category_groups, degrees, event_appearances, events, funding_rounds, funds, investments, ipos, jobs, market_insights, micro_categories, organizations, ownerships, people. | +| `entityId` | string | Yes | Entity permalink or UUID | +| `cardId` | string | Yes | Card to page through, e.g. "participated_investments" on a person, "founders" on an organization, or "investors" on a funding round. Valid ids differ per collection. | +| `cardFieldIds` | json | No | Fields to return on each card item, e.g. \["identifier","announced_on","money_raised"\]. The identifier is always requested alongside these, because the next-page cursor is read from it. | +| `cardOrder` | string | No | Sort expression for the card, e.g. "funding_round_money_raised desc" | +| `limit` | number | No | Card items to return per page, 1-100 | +| `afterId` | string | No | UUID of the last card item on the current page, to fetch the next page | +| `beforeId` | string | No | UUID of the first card item on the current page, to fetch the previous page | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `items` | json | Card items for this page, each holding the requested card_field_ids | +| `properties` | json | Properties of the parent entity returned alongside the card | +| `nextAfterId` | string | UUID of the last card item, to pass as afterId for the next page | + +### Crunchbase Autocomplete + +Suggest Crunchbase entities matching a typed query, returning the permalinks and UUIDs the lookup and search operations take. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Crunchbase API key, sent as the X-cb-user-key header | +| `query` | string | Yes | Text to autocomplete against, e.g. "airbnb" | +| `collectionIds` | json | No | Collections to search, e.g. \["organizations","people"\]. One or more of: addresses, categories, category_groups, degrees, diversity_spotlights, event_appearances, events, ipos, jobs, locations, organizations, ownerships, people, principals. Defaults to every collection. | +| `limit` | number | No | Suggestions to return, max 25 \(default 10\) | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `entities` | json | Suggestions as \[\{identifier: \{uuid, value, permalink, image_id, entity_def_id\}, facet_ids, short_description\}\] | + +### Crunchbase List Deleted Entities + +List entities Crunchbase has deleted, so a mirrored copy can be pruned in step with the source. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Crunchbase API key, sent as the X-cb-user-key header | +| `collection` | string | No | Restrict the feed to a single collection: categories, event_appearances, events, ipos, jobs, locations, organizations, ownerships, or people. Leave empty to read the feed across collections. | +| `collectionIds` | json | No | Collections to include when reading the cross-collection feed, e.g. \["organizations","people"\]. Ignored when a single collection is set. | +| `deletedAtOrder` | string | No | Order by deletion time: "asc" \(default\) or "desc" | +| `limit` | number | No | Rows to return per page | +| `afterId` | string | No | UUID of the last row on the current page, to fetch the next page | +| `beforeId` | string | No | UUID of the first row on the current page, to fetch the previous page | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `entities` | json | Deleted entities as \[\{deleted_at, identifier: \{uuid, value, permalink, entity_def_id\}\}\] | +| `nextAfterId` | string | UUID of the last row, to pass as afterId for the next page | + +### Crunchbase Get Fields Metadata + +List the field ids, types, and descriptions each Crunchbase collection publishes, which is how the field_ids and query predicates of the other operations are discovered. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Crunchbase API key, sent as the X-cb-user-key header | +| `collectionIds` | json | No | Collections to describe, e.g. \["organizations","people"\]. One or more of: addresses, categories, category_groups, degrees, diversity_spotlights, event_appearances, events, ipos, jobs, locations, organizations, ownerships, people, principals. Defaults to every collection. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `csv` | string | Field metadata as CSV, one row per field with its collection, id, type, and description | + + diff --git a/apps/docs/content/docs/en/integrations/granola.mdx b/apps/docs/content/docs/en/integrations/granola.mdx index 48244a625bc..1085c239441 100644 --- a/apps/docs/content/docs/en/integrations/granola.mdx +++ b/apps/docs/content/docs/en/integrations/granola.mdx @@ -1,6 +1,6 @@ --- title: Granola -description: Access meeting notes and transcripts from Granola +description: Access meeting notes, transcripts, and audit events from Granola --- import { BlockInfoCard } from "@/components/ui/block-info-card" @@ -25,7 +25,7 @@ In Sim, the Granola integration allows your agents to pull meeting notes, summar ## Usage Instructions -Integrate Granola into your workflow to retrieve meeting notes, summaries, attendees, and transcripts. +Integrate Granola into your workflow to retrieve meeting notes, summaries, attendees, and transcripts, review workspace audit events, and manage webhook endpoints. Granola can also trigger workflows when notes are generated, edited, or shared with you. @@ -51,7 +51,7 @@ Lists meeting notes from Granola with optional date filters and pagination. | Parameter | Type | Description | | --------- | ---- | ----------- | -| `notes` | json | List of meeting notes | +| `notes` | array | List of meeting notes | | ↳ `id` | string | Note ID | | ↳ `title` | string | Note title | | ↳ `ownerName` | string | Note owner name | @@ -86,10 +86,10 @@ Retrieves a specific meeting note from Granola by ID, including summary, attende | `webUrl` | string | URL to view the note in Granola | | `summaryText` | string | Plain text summary of the meeting | | `summaryMarkdown` | string | Markdown-formatted summary of the meeting | -| `attendees` | json | Meeting attendees | +| `attendees` | array | Meeting attendees | | ↳ `name` | string | Attendee name | | ↳ `email` | string | Attendee email | -| `folders` | json | Folders the note belongs to | +| `folders` | array | Folders the note belongs to | | ↳ `id` | string | Folder ID | | ↳ `name` | string | Folder name | | `calendarEventTitle` | string | Calendar event title | @@ -97,15 +97,44 @@ Retrieves a specific meeting note from Granola by ID, including summary, attende | `calendarEventId` | string | Calendar event ID | | `scheduledStartTime` | string | Scheduled start time | | `scheduledEndTime` | string | Scheduled end time | -| `invitees` | json | Calendar event invitee emails | -| `transcript` | json | Meeting transcript entries \(only if requested\) | +| `invitees` | array | Calendar event invitee emails | +| `transcript` | array | Meeting transcript entries \(only if requested\) | | ↳ `speaker` | string | Speaker source \(microphone or speaker\) | +| ↳ `speakerAttribution` | string | Who spoke relative to the note owner: "me" for the note-taker, "them" for other participants. Null when attribution is unknown. | | ↳ `speakerLabel` | string | Diarization label for the speaker \(e.g., Speaker A\) | | ↳ `speakerName` | string | Resolved name of the identified speaker, when available | | ↳ `text` | string | Transcript text | | ↳ `startTime` | string | Segment start time | | ↳ `endTime` | string | Segment end time | +### Granola Get Transcript + +Retrieves a meeting transcript from Granola one page at a time, including when Get Note reports the transcript is too large to return inline. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Granola API key | +| `noteId` | string | Yes | The note ID \(e.g., not_1d3tmYTlCICgjy\) | +| `cursor` | string | No | Pagination cursor from a previous response | +| `pageSize` | number | No | Number of transcript items per page \(1-100, default 50\) | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `transcript` | array | Transcript items for this page | +| ↳ `speaker` | string | Audio source of the speaker \(microphone or speaker\) | +| ↳ `speakerAttribution` | string | Who spoke relative to the note owner: "me" for the note-taker, "them" for other participants. Null when attribution is unknown. | +| ↳ `speakerLabel` | string | Anonymous diarization label for the speaker \(e.g., Speaker A\) | +| ↳ `speakerName` | string | Resolved name of the identified speaker, when available | +| ↳ `text` | string | Transcript text | +| ↳ `startTime` | string | Segment start time | +| ↳ `endTime` | string | Segment end time | +| `hasMore` | boolean | Whether another page of transcript items is available | +| `cursor` | string | Pagination cursor for the next page | + ### Granola List Folders Lists folders from Granola, sorted alphabetically, with pagination. @@ -122,11 +151,256 @@ Lists folders from Granola, sorted alphabetically, with pagination. | Parameter | Type | Description | | --------- | ---- | ----------- | -| `folders` | json | List of folders | +| `folders` | array | List of folders | | ↳ `id` | string | Folder ID | | ↳ `name` | string | Folder name | | ↳ `parentFolderId` | string | Parent folder ID, or null for top-level folders | | `hasMore` | boolean | Whether more folders are available | | `cursor` | string | Pagination cursor for the next page | +### Granola List Audit Events + +Lists workspace audit events from Granola, with optional action and date filters. Events are returned in collection order and retained for one year. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Granola API key | +| `action` | string | No | Return only events with this exact action, or actions beginning with it followed by a dot \(e.g., "workspace" matches workspace.member_added\). Lowercase. | +| `occurredAfter` | string | No | Return events that occurred after this date \(ISO 8601\). Must fall within the one-year retention window. | +| `occurredBefore` | string | No | Return events that occurred before this date \(ISO 8601\). Must fall within the one-year retention window. | +| `cursor` | string | No | Pagination cursor from a previous response | +| `pageSize` | number | No | Number of audit events per page \(1-30, default 10\) | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `events` | array | List of audit events | +| ↳ `id` | string | Audit event ID | +| ↳ `action` | string | The recorded action \(e.g., workspace.member_added\). Treat as an open set — actions are added over time. | +| ↳ `occurredAt` | string | When the action happened | +| ↳ `collectedAt` | string | When Granola recorded the event. Events are returned in this order, so page on it rather than on occurredAt. | +| ↳ `actorType` | string | Who performed the action: user, api_key, system, or anonymous | +| ↳ `actorId` | string | User ID of the actor, when the actor is a resolvable user | +| ↳ `actorEmail` | string | Email of the acting user, when the account still exists | +| ↳ `data` | json | Action-specific details. Field names are the ones Granola records internally, so they are camelCase. | +| ↳ `ipAddress` | string | IP address the request came from, when recorded | +| ↳ `userAgent` | string | User agent of the client that made the request, when recorded | +| ↳ `clientVersion` | string | Granola client version that made the request, when recorded | +| `hasMore` | boolean | Whether more audit events are available. A page can hold fewer than pageSize events and still not be the last one. | +| `cursor` | string | Pagination cursor for the next page | + +### Granola Create Webhook Endpoint + +Registers an HTTPS URL in Granola to receive note event deliveries. The signing secret is returned only by this operation and cannot be retrieved later. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Granola API key | +| `url` | string | Yes | The publicly reachable HTTPS URL to deliver events to. Private network addresses are rejected. | +| `scopes` | string | Yes | Which notes to receive events for, comma-separated: personal, public. With a workspace API key pass exactly "workspace". | +| `events` | string | No | Event names to subscribe to, comma-separated: note.generated, note.edited, note.access_granted. Omit to subscribe to all events. | +| `folderIds` | string | No | Restrict delivery to notes in these folders or their subfolders, comma-separated folder IDs \(max 100\). Omit for every note matching scopes. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `id` | string | Webhook endpoint ID | +| `url` | string | The HTTPS URL deliveries are sent to | +| `urlRedacted` | boolean | Whether the returned URL was reduced to its origin because the caller is not the endpoint creator | +| `events` | array | Event names this endpoint is subscribed to | +| `folderIds` | array | Folder IDs delivery is restricted to, or an empty array when unrestricted | +| `scopes` | array | Which notes this endpoint receives events for | +| `createdByName` | string | Name of the user who created the endpoint | +| `createdByEmail` | string | Email of the user who created the endpoint | +| `enabled` | boolean | Whether deliveries are active | +| `createdAt` | string | Creation timestamp | +| `signingSecret` | string | Secret for verifying delivery signatures \(Standard Webhooks HMAC-SHA256\). Returned only here — store it securely. | + +### Granola List Webhook Endpoints + +Lists the Granola webhook endpoints the API key can manage. A personal key sees the endpoints it created; a workspace admin sees every endpoint in the workspace. Signing secrets are never included. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Granola API key | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `webhookEndpoints` | array | List of webhook endpoints | +| ↳ `id` | string | Webhook endpoint ID | +| ↳ `url` | string | The HTTPS URL deliveries are sent to, reduced to its origin when urlRedacted is true | +| ↳ `urlRedacted` | boolean | Whether the URL was reduced to its origin because the caller is not the endpoint creator | +| ↳ `events` | array | Event names this endpoint is subscribed to | +| ↳ `folderIds` | array | Folder IDs delivery is restricted to, or an empty array when unrestricted | +| ↳ `scopes` | array | Which notes this endpoint receives events for | +| ↳ `createdByName` | string | Name of the user who created the endpoint | +| ↳ `createdByEmail` | string | Email of the user who created the endpoint | +| ↳ `enabled` | boolean | Whether deliveries are active | +| ↳ `createdAt` | string | Creation timestamp | + +### Granola Update Webhook Endpoint + +Updates a Granola webhook endpoint. Each supplied field replaces its current value; omitted fields are left unchanged. Use enabled to pause or resume deliveries. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Granola API key | +| `webhookEndpointId` | string | Yes | The webhook endpoint ID \(e.g., whe_2mKr8fQxLp7Ta3\) | +| `url` | string | No | New HTTPS URL to deliver events to. Omit to leave unchanged. | +| `scopes` | string | No | Replacement scopes, comma-separated: personal, public. Omit to leave unchanged. A workspace-managed endpoint accepts only "workspace". | +| `events` | string | No | Replacement event subscriptions, comma-separated: note.generated, note.edited, note.access_granted. Omit to leave unchanged. | +| `folderIds` | string | No | Replacement folder filter, comma-separated folder IDs \(max 100\). Pass "\[\]" to remove the filter. Omit to leave unchanged. | +| `enabled` | boolean | No | Pause \(false\) or resume \(true\) deliveries. Events that occur while paused are not delivered later. Omit to leave unchanged. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `id` | string | Webhook endpoint ID | +| `url` | string | The HTTPS URL deliveries are sent to | +| `urlRedacted` | boolean | Whether the returned URL was reduced to its origin because the caller is not the endpoint creator | +| `events` | array | Event names this endpoint is subscribed to | +| `folderIds` | array | Folder IDs delivery is restricted to, or an empty array when unrestricted | +| `scopes` | array | Which notes this endpoint receives events for | +| `createdByName` | string | Name of the user who created the endpoint | +| `createdByEmail` | string | Email of the user who created the endpoint | +| `enabled` | boolean | Whether deliveries are active | +| `createdAt` | string | Creation timestamp | + +### Granola Delete Webhook Endpoint + +Deletes a Granola webhook endpoint by ID, stopping its event deliveries immediately. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Granola API key | +| `webhookEndpointId` | string | Yes | The webhook endpoint ID \(e.g., whe_2mKr8fQxLp7Ta3\) | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `id` | string | ID of the deleted webhook endpoint | +| `deleted` | boolean | Whether the endpoint was deleted | + + + +## Triggers + +A **Trigger** is a block that starts a workflow when an event happens in this service. + +### Granola Events + +Trigger workflow on any Granola note event + +#### Configuration + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Your Granola API key. Used to register the webhook endpoint on deploy and remove it on undeploy. | +| `scopes` | string | No | Comma-separated scopes deciding which notes send events: personal, public. With a Workspace API key pass exactly "workspace". Defaults to "personal, public". | +| `folderIds` | string | No | Optional comma-separated folder IDs \(max 100\). Deliveries are restricted to notes in these folders or their subfolders. Leave blank for every note matching the scopes. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `event_id` | string | Unique ID for the event. Retries of the same delivery reuse it. | +| `event_type` | string | Which event occurred: note.generated, note.edited, or note.access_granted. | +| `note_id` | string | ID of the note the event is about \(e.g., not_1d3tmYTlCICgjy\). Fetch it with the Get Note operation. | +| `occurred_at` | string | ISO 8601 timestamp of when the event occurred. | +| `changed_fields` | json | Note fields that changed. Present on note.edited events \(currently always \["summary"\]\); null otherwise. | +| `payload` | json | Full raw webhook body as delivered by Granola. | + + +--- + +### Granola Note Access Granted + +Trigger workflow when a Granola note is shared with you, directly or via a folder + +#### Configuration + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Your Granola API key. Used to register the webhook endpoint on deploy and remove it on undeploy. | +| `scopes` | string | No | Comma-separated scopes deciding which notes send events: personal, public. With a Workspace API key pass exactly "workspace". Defaults to "personal, public". | +| `folderIds` | string | No | Optional comma-separated folder IDs \(max 100\). Deliveries are restricted to notes in these folders or their subfolders. Leave blank for every note matching the scopes. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `event_id` | string | Unique ID for the event. Retries of the same delivery reuse it. | +| `event_type` | string | Which event occurred: note.generated, note.edited, or note.access_granted. | +| `note_id` | string | ID of the note the event is about \(e.g., not_1d3tmYTlCICgjy\). Fetch it with the Get Note operation. | +| `occurred_at` | string | ISO 8601 timestamp of when the event occurred. | +| `changed_fields` | json | Note fields that changed. Present on note.edited events \(currently always \["summary"\]\); null otherwise. | +| `payload` | json | Full raw webhook body as delivered by Granola. | + + +--- + +### Granola Note Edited + +Trigger workflow when a Granola note summary is edited or regenerated + +#### Configuration + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Your Granola API key. Used to register the webhook endpoint on deploy and remove it on undeploy. | +| `scopes` | string | No | Comma-separated scopes deciding which notes send events: personal, public. With a Workspace API key pass exactly "workspace". Defaults to "personal, public". | +| `folderIds` | string | No | Optional comma-separated folder IDs \(max 100\). Deliveries are restricted to notes in these folders or their subfolders. Leave blank for every note matching the scopes. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `event_id` | string | Unique ID for the event. Retries of the same delivery reuse it. | +| `event_type` | string | Which event occurred: note.generated, note.edited, or note.access_granted. | +| `note_id` | string | ID of the note the event is about \(e.g., not_1d3tmYTlCICgjy\). Fetch it with the Get Note operation. | +| `occurred_at` | string | ISO 8601 timestamp of when the event occurred. | +| `changed_fields` | json | Note fields that changed. Present on note.edited events \(currently always \["summary"\]\); null otherwise. | +| `payload` | json | Full raw webhook body as delivered by Granola. | + + +--- + +### Granola Note Generated + +Trigger workflow when the first AI summary for a Granola note is generated + +#### Configuration + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | Your Granola API key. Used to register the webhook endpoint on deploy and remove it on undeploy. | +| `scopes` | string | No | Comma-separated scopes deciding which notes send events: personal, public. With a Workspace API key pass exactly "workspace". Defaults to "personal, public". | +| `folderIds` | string | No | Optional comma-separated folder IDs \(max 100\). Deliveries are restricted to notes in these folders or their subfolders. Leave blank for every note matching the scopes. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `event_id` | string | Unique ID for the event. Retries of the same delivery reuse it. | +| `event_type` | string | Which event occurred: note.generated, note.edited, or note.access_granted. | +| `note_id` | string | ID of the note the event is about \(e.g., not_1d3tmYTlCICgjy\). Fetch it with the Get Note operation. | +| `occurred_at` | string | ISO 8601 timestamp of when the event occurred. | +| `changed_fields` | json | Note fields that changed. Present on note.edited events \(currently always \["summary"\]\); null otherwise. | +| `payload` | json | Full raw webhook body as delivered by Granola. | diff --git a/apps/docs/content/docs/en/integrations/meta.json b/apps/docs/content/docs/en/integrations/meta.json index a5ef9d8e37e..bf435caffba 100644 --- a/apps/docs/content/docs/en/integrations/meta.json +++ b/apps/docs/content/docs/en/integrations/meta.json @@ -24,6 +24,7 @@ "attio-service-account", "azure_data_explorer", "azure_devops", + "bitbucket", "box", "box-service-account", "brandfetch", @@ -34,6 +35,7 @@ "calcom", "calcom-service-account", "calendly", + "cbinsights", "circleback", "clay", "clerk", @@ -48,6 +50,7 @@ "context_dev", "convex", "crowdstrike", + "crunchbase", "cursor", "dagster", "databricks", @@ -187,6 +190,7 @@ "pinecone", "pipedrive", "pipedrive-service-account", + "pitchbook", "polymarket", "postgresql", "posthog", diff --git a/apps/docs/content/docs/en/integrations/pitchbook.mdx b/apps/docs/content/docs/en/integrations/pitchbook.mdx new file mode 100644 index 00000000000..7c7de8913eb --- /dev/null +++ b/apps/docs/content/docs/en/integrations/pitchbook.mdx @@ -0,0 +1,3484 @@ +--- +title: PitchBook +description: Look up private market data on companies, deals, investors, funds, and people +--- + +import { BlockInfoCard } from "@/components/ui/block-info-card" + + + +{/* MANUAL-CONTENT-START:intro */} +[PitchBook](https://pitchbook.com/) is a private capital market database covering companies, deals, investors, funds, limited partners, and the people behind them. The PitchBook API is a separate, contracted add-on to a platform subscription — every call spends credits from a purchased balance. + +With the PitchBook integration in Sim, you can: + +- **Search every entity type**: Resolve a name, website, or ticker to a PitchBook ID, or run a filtered search across companies, deals, investors, people, funds, limited partners, and service providers +- **Profile companies**: Pull firmographics, industries and verticals, the full investor list, complete deal history, latest financing and debt financing, reported financials, similar companies, VC exit predictions, and web/social growth metrics +- **Dig into deals**: Read deal summaries and full detail, valuations and multiples, participating investors and exiters, share terms, cap table history, funding tranches, and debt with its lenders +- **Track investors and funds**: Fetch investor profiles, holdings, managed funds, board seats, and stated investment preferences, plus fund performance, peer benchmarks, cash flows, commitments, and team +- **Map limited partners**: Retrieve commitment history and totals by fund type, commitment preferences, and actual versus target asset allocations +- **Research people and patents**: Look up biographies, contact details, education and work history, and search a company's patent portfolio +- **Follow credit markets**: Search PitchBook credit analysis news, or pull single and bulk articles in full +- **Sync incrementally**: Ask any entity which of its datasets changed in a window, so a scheduled workflow only refetches what actually moved +- **Watch your spend**: Report credit usage, contract balances, per-endpoint call costs, and the lookup-table codes the search filters expect + +### Authentication + +PitchBook uses an API key sent as `Authorization: PB-Token {key}`, not a bearer token. Keys are issued by your PitchBook account team alongside a credit balance; a sandbox key is available for testing, and the **List Sandbox Entities** operation returns the IDs that key is allowed to query. + +### Working with filters + +PitchBook range filters carry their operator inside the value rather than as a separate parameter: + +| Filter | Meaning | +| --- | --- | +| `>2024-01-01` | after a date | +| `<2024-01-01` | before a date | +| `2023-01-01^2024-01-01` | between two dates | +| `>100` | greater than 100 | +| `10^100` | between 10 and 100 | + +Amounts are in millions. Codes such as industries, verticals, and deal types are not free text — use **List Lookup Tables** to find the right table, then **Get Lookup Table Codes** to read its values. Any documented filter without a dedicated field can be passed through **Additional Filters** as a JSON object. + +In Sim, the PitchBook integration lets agents research private markets as part of an automated workflow — resolving a company to its PitchBook ID, assembling a diligence brief, screening investors against an ideal profile, or posting a scheduled deal-flow digest to the team. +{/* MANUAL-CONTENT-END */} + + +## Usage Instructions + +Integrates the PitchBook Public API into the workflow. Search and pull profiles across companies, deals, investors, people, funds, limited partners, and service providers, including financing history, valuations, cap tables, debt and lenders, fund performance and commitments, patents, and credit analysis news. Also reports API credit usage and the lookup-table codes the search filters expect. Every call consumes PitchBook API credits. + + + +## Actions + +### PitchBook Search + +Search across every PitchBook entity type at once by name, PitchBook ID, website, or ticker. Use this to resolve a company, investor, or fund to its PitchBook ID before calling a profile operation. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `query` | string | Yes | What to look up: an entity name, a PitchBook ID, a website, a ticker, or an exchange-qualified ticker. Names and websites match partially once the term is long enough; IDs and tickers match exactly. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | +| `page` | number | No | Page of results to return, starting at 1 | +| `perPage` | number | No | How many results to return per page | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `stats` | object | Paging envelope for the result set | +| ↳ `total` | number | Total number of matching results | +| ↳ `perPage` | number | Results returned per page | +| ↳ `page` | number | Current page number | +| ↳ `lastPage` | number | Number of the last available page | +| `items` | array | Matching entities. Entries carry pbId/name for companies, investors, and service providers, and fundId/fundName for funds, so check which is populated before using an ID. | +| ↳ `pbId` | string | PitchBook entity ID, null for fund results | +| ↳ `name` | string | Entity name, null for fund results | +| ↳ `fundId` | string | PitchBook fund ID, present only on fund results | +| ↳ `fundName` | string | Fund name, present only on fund results | +| ↳ `website` | string | Entity website, absent on fund results | +| ↳ `pitchBookProfileLink` | string | Link to the entity profile in the PitchBook platform | +| ↳ `primaryFirmType` | object | Primary type of the entity | +| ↳ `pbId` | string | PitchBook entity ID | +| ↳ `type` | string | Entity type \(e.g. COMPANY, INVESTOR\) | +| ↳ `otherFirmTypes` | array | Additional types the entity is also classified as | +| ↳ `pbId` | string | PitchBook entity ID | +| ↳ `type` | string | Entity type \(e.g. COMPANY, INVESTOR\) | +| ↳ `stockTicker` | string | Stock ticker when the entity is publicly traded | + +### PitchBook Shared Search + +Extract the names and PitchBook IDs behind an Advanced Search shared from the PitchBook platform, using the search ID and hash from the shared link + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `entityType` | string | Yes | Entity type the shared search returns: COMPANIES, DEALS, INVESTORS, SERVICE_PROVIDERS, LIMITED_PARTNERS, PEOPLE, ENTITY_MANAGEMENT, or FUNDS | +| `searchId` | string | Yes | Search ID from the shared link, the path segment after /search/ \(e.g. 8e6bd17e-dea5-4eca-8143-dddb2ab623a0\) | +| `hash` | string | Yes | Hash query parameter from the shared link | +| `page` | number | No | Page of results to return, starting at 1 | +| `perPage` | number | No | How many results to return per page | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `stats` | object | Summary statistics for the response | +| ↳ `total` | number | Total number of matching results | +| ↳ `perPage` | number | Results returned per page | +| ↳ `page` | number | Current page number | +| ↳ `lastPage` | number | Number of the last available page | +| `searchCriteria` | string | Criteria of the shared search | +| `items` | array | Records returned | +| ↳ `companyId` | string | PitchBook company ID | +| ↳ `companyName` | string | Company name | +| ↳ `website` | string | Website | + +### PitchBook Entity People + +Retrieve the people at an entity: primary contact, current and former team, and current and former board members + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook entity ID of a company, investor, or service provider, e.g. 51261-67. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `entityId` | string | PitchBook entity ID | +| `primaryContact` | object | Primary contact at the entity | +| ↳ `personId` | string | PitchBook person ID | +| ↳ `fullName` | string | Full name | +| ↳ `title` | string | Job title | +| ↳ `phone` | string | Phone number | +| ↳ `fax` | string | Fax number | +| ↳ `email` | string | Email address | +| `currentTeam` | array | People currently working at the entity | +| ↳ `id` | string | PitchBook person ID | +| ↳ `name` | string | Full name | +| ↳ `title` | string | Job title | +| ↳ `positionStart` | string | Date the position started \(YYYY-MM-DD\) | +| ↳ `infoAvailable` | boolean | Whether a full person profile is available for them | +| `formerTeam` | array | People who previously worked at the entity | +| ↳ `id` | string | PitchBook person ID | +| ↳ `name` | string | Full name | +| ↳ `title` | string | Job title | +| ↳ `positionStart` | string | Date the position started \(YYYY-MM-DD\) | +| ↳ `positionFinish` | string | Date the position ended \(YYYY-MM-DD\) | +| ↳ `infoAvailable` | boolean | Whether a full person profile is available for them | +| `currentBoardMembersAndObservers` | array | Current board members and observers | +| `formerBoardMembersAndObservers` | array | Former board members and observers | + +### PitchBook Entity Locations + +Retrieve the headquarters and every alternate office on record for an entity + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook entity ID of a company, investor, or service provider, e.g. 51261-67. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `entityId` | string | PitchBook entity ID | +| `hqOffice` | object | Headquarters office | +| ↳ `location` | string | Office label | +| ↳ `addressLine1` | string | Address line 1 | +| ↳ `addressLine2` | json | Address line 2 | +| ↳ `city` | string | City | +| ↳ `stateProvince` | string | State or province | +| ↳ `postCode` | string | Postal code | +| ↳ `country` | string | Country | +| ↳ `phone` | string | Phone number | +| ↳ `fax` | json | Fax number | +| ↳ `email` | string | Email address | +| ↳ `globalRegion` | string | Global region | +| ↳ `globalSubRegion` | string | Global sub-region | +| `alternateOffices` | array | Other offices on record | +| ↳ `location` | string | Office label | +| ↳ `addressLine1` | string | Address line 1 | +| ↳ `addressLine2` | string | Address line 2 | +| ↳ `city` | string | City | +| ↳ `stateProvince` | string | State or province | +| ↳ `postCode` | string | Postal code | +| ↳ `country` | string | Country | +| ↳ `phone` | json | Phone number | +| ↳ `fax` | json | Fax number | +| ↳ `email` | string | Email address | +| ↳ `globalRegion` | string | Global region | +| ↳ `globalSubRegion` | string | Global sub-region | +| `alternateOfficesCount` | number | How many other offices are on record | + +### PitchBook Entity Affiliates + +Retrieve the affiliated entities linked to an entity and how each is related + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook entity ID of a company, investor, or service provider, e.g. 51261-67. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `affiliates` | array | Entities affiliated with the given entity | +| ↳ `entityId` | string | PitchBook entity ID | +| ↳ `affiliateId` | string | PitchBook ID of the affiliate | +| ↳ `affiliateName` | string | Name of the affiliate | +| ↳ `affiliateType` | string | Relationship to the affiliate | + +### PitchBook Entity News + +Retrieve recent news articles PitchBook has associated with an entity + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook entity ID of a company, investor, or service provider, e.g. 51261-67. | +| `sinceDate` | string | No | Publication window, carrying its operator in the value: >YYYY-MM-DD for after a date, <YYYY-MM-DD for before one, or YYYY-MM-DD^YYYY-MM-DD for a range. Use this or trailingRange. | +| `trailingRange` | number | No | How many days back to pull news for \(e.g. 20\) | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `news` | array | News articles associated with the entity, most recent first | +| ↳ `entityId` | string | PitchBook entity ID the article is about | +| ↳ `title` | string | Article headline | +| ↳ `byline` | string | Article summary or byline | +| ↳ `source` | string | Publication the article came from | +| ↳ `publishDate` | string | Publication timestamp \(ISO 8601\) | +| ↳ `url` | string | Link to the article | + +### PitchBook Entity Updates + +Check which entity datasets changed in a window, so a sync only refetches what moved + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook entity ID of a company, investor, or service provider, e.g. 51261-67. | +| `sinceDate` | string | No | Window to report changes over, carrying its operator in the value: >YYYY-MM-DD for after a date, <YYYY-MM-DD for before one, or YYYY-MM-DD^YYYY-MM-DD for a range. Use this or trailingRange. | +| `trailingRange` | number | No | Report changes over the last N days. Use this or sinceDate. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `updates` | json | Map of dataset name to whether it changed in the window. Keys are PitchBook dataset names, so read it as a plain object. | + +### PitchBook Company Search + +Search PitchBook for companies by name, location, industry, funding, deal activity, and more + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `companyNames` | string | No | Comma-separated company names, PitchBook IDs, websites, or tickers | +| `keywords` | string | No | Keywords associated with the company or appearing in its business description | +| `city` | string | No | City the company is located in | +| `stateProvince` | string | No | State or province the company is located in | +| `country` | string | No | Country the company is located in \(e.g. USA\) | +| `locationType` | string | No | Restrict location matching to HQ_ONLY, NON_HQ_ONLY, or ANY | +| `ownershipStatus` | string | No | PitchBook ownership status code | +| `businessStatus` | string | No | PitchBook business status code | +| `dateFounded` | string | No | Founding date filter. Use >YYYY-MM-DD, <YYYY-MM-DD, or YYYY-MM-DD^YYYY-MM-DD for a range | +| `industry` | string | No | PitchBook industry code | +| `verticals` | string | No | PitchBook vertical code | +| `dealType` | string | No | PitchBook deal type code \(e.g. evc for early-stage VC\) | +| `dealSize` | string | No | Deal size in millions. Use >100, <100, or 10^100 for a range | +| `dealDate` | string | No | Deal date filter. Use >YYYY-MM-DD, <YYYY-MM-DD, or YYYY-MM-DD^YYYY-MM-DD for a range | +| `totalRaised` | string | No | Total raised to date in millions. Use >100, <100, or 10^100 for a range | +| `investorNames` | string | No | Comma-separated investor names, PitchBook IDs, websites, or tickers | +| `employeeCount` | string | No | Employee count. Use >100, <100, or 10^100 for a range | +| `revenue` | string | No | Revenue in millions. Use >100, <100, or 10^100 for a range | +| `filterCurrency` | string | No | ISO currency code the monetary filters on this search are expressed in, e.g. setting EUR means dealSize is read as millions of euros. Distinct from `currency`, which converts the values PitchBook returns. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | +| `page` | number | No | Page of results to return, starting at 1 | +| `perPage` | number | No | How many results to return per page | +| `additionalFilters` | json | No | Any other documented search filter, as a JSON object of query parameter names to values \(e.g. \{"emergingSpaces": "AGTECH"\}\). A dedicated field always wins over the same key set here. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `stats` | object | Paging envelope for the result set | +| ↳ `total` | number | Total number of matching results | +| ↳ `perPage` | number | Results returned per page | +| ↳ `page` | number | Current page number | +| ↳ `lastPage` | number | Number of the last available page | +| `items` | array | Companies matching the search criteria | +| ↳ `companyId` | string | PitchBook company ID | +| ↳ `companyName` | string | Company name | +| ↳ `website` | string | Company website | + +### PitchBook Company Bio + +Retrieve the core profile of a company: names, description, HQ, status, headcount, total raised, and social links + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook company ID, e.g. 10618-03. Use PitchBook Search to resolve a name to an ID. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `companyId` | string | PitchBook company ID | +| `companyName` | object | The names the company is known by | +| ↳ `formalName` | string | Formal name | +| ↳ `alsoKnownAs` | string | Also-known-as name | +| ↳ `legalName` | string | Registered legal name | +| ↳ `formerlyKnownAs` | string | Previous name | +| `parentCompanyId` | string | PitchBook ID of the parent company | +| `parentCompanyName` | string | Name of the parent company | +| `hqLocation` | object | Headquarters location | +| ↳ `city` | string | City | +| ↳ `stateProvince` | string | State or province | +| ↳ `postCode` | string | Postal code | +| ↳ `country` | string | Country | +| `description` | string | Business description | +| `financingStatus` | object | How the company is financed | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `businessStatus` | object | Operating status of the business | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `ownershipStatus` | object | Ownership status of the company | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `universe` | array | PitchBook universes the company belongs to | +| ↳ `code` | string | Universe code | +| ↳ `description` | string | Universe label | +| `website` | string | Company website | +| `employees` | number | Current employee count | +| `employeeHistory` | array | Reported headcount over time | +| ↳ `asOfDate` | string | Date the count was reported \(YYYY-MM-DD\) | +| ↳ `employeeCount` | number | Headcount on that date | +| `exchange` | string | Stock exchange the company trades on | +| `ticker` | string | Stock ticker | +| `yearFounded` | number | Year the company was founded | +| `financingStatusNote` | object | Analyst note explaining the financing status | +| ↳ `note` | string | Note text | +| ↳ `asOfDate` | string | Date of the note \(YYYY-MM-DD\) | +| `totalMoneyRaised` | object | Total capital raised to date | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `sicCodes` | array | SIC classification codes | +| ↳ `code` | string | SIC code | +| ↳ `description` | string | SIC code label | +| `morningstarCode` | string | Morningstar identifier | +| `cikCode` | string | SEC CIK identifier | +| `companySocialURLs` | object | Social profile links | +| ↳ `facebookProfileUrl` | string | Facebook profile | +| ↳ `twitterProfileUrl` | string | X/Twitter profile | +| ↳ `linkedInProfileUrl` | string | LinkedIn profile | +| `pitchBookProfileLink` | string | Link to the company profile in the PitchBook platform | + +### PitchBook Company Industries + +Retrieve the industry classification, verticals, keywords, and emerging spaces assigned to a company + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook company ID, e.g. 10618-03. Use PitchBook Search to resolve a name to an ID. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `companyId` | string | PitchBook company ID | +| `industries` | array | Industry classifications, most specific first. One entry is flagged primary. | +| ↳ `industrySector` | object | Top-level sector | +| ↳ `code` | string | Sector code | +| ↳ `description` | string | Sector label | +| ↳ `industryGroup` | object | Industry group within the sector | +| ↳ `code` | string | Group code | +| ↳ `description` | string | Group label | +| ↳ `industryCode` | object | Most specific industry classification | +| ↳ `code` | string | Industry code | +| ↳ `description` | string | Industry label | +| ↳ `primary` | boolean | Whether this is the primary industry | +| `verticals` | array | Verticals the company operates in | +| ↳ `code` | string | Vertical code | +| ↳ `description` | string | Vertical label | +| `keywords` | array | Keywords associated with the company | +| `emergingSpaces` | array | Analyst-defined emerging spaces the company is placed in | +| ↳ `code` | string | Emerging space code | +| ↳ `description` | string | Emerging space label | + +### PitchBook Company Investors + +Retrieve every investor in a company, current and former, with the type of investor and when they invested + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook company ID, e.g. 10618-03. Use PitchBook Search to resolve a name to an ID. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `countAllInvestors` | number | Total number of investors on record | +| `investors` | array | Investors in the company, current and former | +| ↳ `companyId` | string | PitchBook company ID | +| ↳ `investorId` | string | PitchBook investor ID | +| ↳ `investorName` | string | Investor name | +| ↳ `investorTypes` | array | Types the investor is classified as, one flagged primary | +| ↳ `type` | object | Investor type | +| ↳ `code` | string | Investor type code | +| ↳ `description` | string | Investor type label | +| ↳ `primary` | boolean | Whether this is the primary type | +| ↳ `investorSince` | string | Date the investor first invested \(YYYY-MM-DD\) | +| ↳ `investorExit` | string | Date the investor exited \(YYYY-MM-DD\) | +| ↳ `investorStatus` | object | Whether the investor is current or former | +| ↳ `code` | string | Status code | +| ↳ `description` | string | Status label | + +### PitchBook Company Active Investors + +Retrieve only the investors currently holding a position in a company + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook company ID, e.g. 10618-03. Use PitchBook Search to resolve a name to an ID. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `activeInvestors` | array | Investors currently holding a position in the company | +| ↳ `companyId` | string | PitchBook company ID | +| ↳ `investorId` | string | PitchBook investor ID | +| ↳ `investorName` | string | Investor name | +| ↳ `investorTypes` | array | Types the investor is classified as, one flagged primary | +| ↳ `primary` | boolean | Whether this is the primary entry | +| ↳ `type` | object | Type as a code and description pair | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| ↳ `investorSince` | string | Date the investor first invested \(YYYY-MM-DD\) | +| ↳ `holding` | string | Current holding status | + +### PitchBook Company Deals + +Retrieve every deal a company has been involved in, in chronological order with its deal type + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook company ID, e.g. 10618-03. Use PitchBook Search to resolve a name to an ID. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `deals` | array | Deals involving the company, oldest first | +| ↳ `companyId` | string | PitchBook company ID | +| ↳ `dealId` | string | PitchBook deal ID | +| ↳ `dealDate` | string | Date of the deal \(YYYY-MM-DD\) | +| ↳ `dealType1` | object | Primary deal type | +| ↳ `code` | string | Deal type code | +| ↳ `description` | string | Deal type label | +| ↳ `dealType2` | object | Secondary deal type, such as the round letter | +| ↳ `code` | string | Deal type code | +| ↳ `description` | string | Deal type label | +| ↳ `dealType3` | object | Tertiary deal type | +| ↳ `code` | string | Deal type code | +| ↳ `description` | string | Deal type label | +| ↳ `dealNumber` | number | Sequence of this deal in the company financing history | + +### PitchBook Company Most Recent Financing + +Retrieve a company most recent financing round: date, size, type, and last known valuation + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook company ID, e.g. 10618-03. Use PitchBook Search to resolve a name to an ID. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `companyId` | string | PitchBook company ID | +| `lastFinancingDealId` | string | PitchBook deal ID of the most recent financing | +| `lastFinancingDate` | string | Date of the most recent financing \(YYYY-MM-DD\) | +| `lastFinancingSize` | object | Size of the most recent financing | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `lastFinancingSizeStatus` | string | Whether the financing size is actual or estimated | +| `lastFinancingValuation` | object | Valuation at the most recent financing | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `lastFinancingValuationStatus` | string | Whether the valuation is actual or estimated | +| `lastFinancingDealType` | object | Primary deal type of the most recent financing | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `lastFinancingDealType2` | object | Secondary deal type of the most recent financing | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `lastFinancingDealType3` | object | Tertiary deal type of the most recent financing | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `lastFinancingDealClass` | object | Deal class of the most recent financing | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `lastKnownValuation` | object | Most recent known valuation of the company | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `lastKnownValuationDate` | string | Date of the last known valuation \(YYYY-MM-DD\) | +| `lastKnownValuationDealType` | object | Deal type the last known valuation came from | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | + +### PitchBook Company Most Recent Debt Financing + +Retrieve a company most recent debt financing, including each debt instrument raised + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook company ID, e.g. 10618-03. Use PitchBook Search to resolve a name to an ID. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `companyId` | string | PitchBook company ID | +| `lastDebtFinancingDealId` | string | PitchBook deal ID of the most recent debt financing | +| `lastDebtFinancingDate` | string | Date of the most recent debt financing \(YYYY-MM-DD\) | +| `lastDebtFinancing` | array | Debt instruments in the most recent debt financing | +| ↳ `lastDebtFinancingType` | object | Type of the most recent debt financing | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `lastDebtFinancingAmount` | object | Amount of the most recent debt financing | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `seniority` | json | Seniority of the debt | +| ↳ `security` | json | Security backing the debt | +| ↳ `subordination` | json | Subordination terms | +| ↳ `term` | json | Term of the debt | +| ↳ `additionalDebtCharacteristics` | object | Other characteristics of the debt | +| ↳ `unitranche` | boolean | Whether the debt is unitranche | +| ↳ `syndicated` | boolean | Whether the debt is syndicated | +| ↳ `mezzanine` | boolean | Whether the debt is mezzanine | +| ↳ `covLite` | boolean | Whether the debt is covenant-lite | +| ↳ `warrants` | boolean | Whether warrants are attached | +| ↳ `convertible` | boolean | Whether the instrument is convertible | +| ↳ `rate` | json | Interest rate | +| ↳ `lenders` | array | Lenders on the debt | + +### PitchBook Company Most Recent Financials + +Retrieve the most recent reported financials for a private company: revenue, net income, EBITDA, assets, and debt + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook company ID, e.g. 10618-03. Use PitchBook Search to resolve a name to an ID. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `companyId` | string | PitchBook company ID | +| `period` | number | Fiscal period the figures cover | +| `endDate` | string | Period end date \(YYYY-MM-DD\) | +| `enterpriseValue` | object | Enterprise value | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `revenue` | object | Revenue | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `netIncome` | object | Net income | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `ebitda` | object | EBITDA | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `totalAssets` | object | Total assets | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `totalDebt` | object | Total debt | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | + +### PitchBook Company Financials + +Retrieve reported financials for a private company across every available fiscal period. Annual data is returned by default. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook company ID, e.g. 10618-03. Use PitchBook Search to resolve a name to an ID. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `companyId` | string | PitchBook company ID | +| `items` | array | Records returned | +| ↳ `period` | string | Fiscal period the figures cover | +| ↳ `endDate` | string | End date \(YYYY-MM-DD\) | +| ↳ `enterpriseValue` | object | Enterprise value | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `currency` | string | Currency of amount | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `revenue` | object | Revenue | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `currency` | string | Currency of amount | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `netIncome` | object | Net income | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `currency` | string | Currency of amount | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `ebitda` | object | EBITDA | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `currency` | string | Currency of amount | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `totalAssets` | object | Total assets | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `currency` | string | Currency of amount | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `totalDebt` | object | Total debt | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `currency` | string | Currency of amount | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | + +### PitchBook Similar Companies + +Retrieve companies PitchBook scores as similar to a given company, flagging which are direct competitors + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook company ID, e.g. 10618-03. Use PitchBook Search to resolve a name to an ID. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `similarCompanies` | array | Similar companies, most similar first | +| ↳ `companyId` | string | PitchBook ID of the company compared against | +| ↳ `similarCompanyId` | string | PitchBook ID of the similar company | +| ↳ `similarCompanyName` | string | Name of the similar company | +| ↳ `similarityScore` | number | Similarity score between 0 and 1, higher is more similar | +| ↳ `competitor` | boolean | Whether PitchBook classifies the company as a direct competitor | + +### PitchBook VC Exit Predictions + +Retrieve PitchBook machine-learning exit predictions for a VC-backed company. Requires at least two funding rounds in the past six years. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook company ID, e.g. 10618-03. Use PitchBook Search to resolve a name to an ID. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `companyId` | string | PitchBook company ID | +| `predictionDate` | string | Date the prediction was generated \(YYYY-MM-DD\) | +| `opportunityScore` | number | PitchBook opportunity score | +| `successClass` | string | Predicted outcome class, such as Success | +| `successProbability` | number | Probability of a successful outcome, as a percentage | +| `noexitProbability` | number | Probability of no exit, as a percentage | +| `exitClass` | string | Most likely exit type, such as IPO or M&A | +| `ipoProbability` | number | Probability of an IPO exit, as a percentage | +| `mergeracquisitionProbability` | number | Probability of an M&A exit, as a percentage | +| `vcDealNumber` | number | Number of VC deals the prediction is based on | + +### PitchBook Company Social Analytics + +Retrieve web and social growth and size metrics for a company, with percentile ranks + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook company ID, e.g. 10618-03. Use PitchBook Search to resolve a name to an ID. | +| `compare` | string | No | Benchmark the signals against a peer set: SIMILAR_COMPANIES, INDUSTRY, VERTICALS, or ALL_COMPANIES | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `companyId` | string | PitchBook company ID | +| `growthRate` | number | Overall growth rate | +| `growthRatePercentile` | number | Percentile of the overall growth rate | +| `growthRateChange` | number | Change in the overall growth rate | +| `growthRatePercentChange` | number | Percent change in the overall growth rate | +| `webGrowthRate` | number | Web traffic growth rate | +| `webGrowthRatePercentile` | number | Percentile of the web growth rate | +| `socialGrowthRate` | number | Social following growth rate | +| `socialGrowthRatePercentile` | number | Percentile of the social growth rate | +| `sizeMultiple` | number | Overall size multiple | +| `sizeMultiplePercentile` | number | Percentile of the size multiple | +| `sizeMultipleChange` | number | Change in the size multiple | +| `sizeMultiplePercentChange` | number | Percent change in the size multiple | +| `webSizeMultiple` | number | Web size multiple | +| `webSizeMultiplePercentile` | number | Percentile of the web size multiple | +| `socialSizeMultiple` | number | Social size multiple | +| `socialSizeMultiplePercentile` | number | Percentile of the social size multiple | +| `twitterFollowers` | number | Twitter/X follower count | +| `twitterFollowersChange` | number | Change in follower count | +| `twitterFollowersPercentChange` | number | Percent change in follower count | + +### PitchBook Company General Service Providers + +Retrieve the current and former general service providers engaged by a company + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook company ID, e.g. 10618-03. Use PitchBook Search to resolve a name to an ID. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `companyId` | string | PitchBook company ID | +| `currentGeneralServices` | array | Current general service relationships | +| ↳ `serviceProviderId` | string | PitchBook service provider ID | +| ↳ `serviceProviderName` | string | Service provider name | +| ↳ `serviceProviderTypes` | array | Types the service provider is classified as | +| ↳ `primary` | boolean | Whether this is the primary entry | +| ↳ `type` | object | Type as a code and description pair | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| ↳ `serviceProvided` | object | Service provided, as a code and description pair | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| `formerGeneralServices` | array | Former general service relationships | +| ↳ `serviceProviderId` | string | PitchBook service provider ID | +| ↳ `serviceProviderName` | string | Service provider name | +| ↳ `serviceProviderTypes` | array | Types the service provider is classified as | +| ↳ `primary` | boolean | Whether this is the primary entry | +| ↳ `type` | object | Type as a code and description pair | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| ↳ `serviceProvided` | object | Service provided, as a code and description pair | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | + +### PitchBook Company Deal Service Providers + +Retrieve the service providers that worked on a company deals, and what each was hired for + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook company ID, e.g. 10618-03. Use PitchBook Search to resolve a name to an ID. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `dealServiceProviders` | array | Service providers engaged on the company deals | +| ↳ `serviceProviderId` | string | PitchBook service provider ID | +| ↳ `serviceProviderName` | string | Service provider name | +| ↳ `serviceProviderTypes` | array | Types the service provider is classified as | +| ↳ `primary` | boolean | Whether this is the primary entry | +| ↳ `type` | object | Type as a code and description pair | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| ↳ `serviceProvided` | object | Service provided, as a code and description pair | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| ↳ `dealIdServiceProvided` | string | PitchBook deal ID the service was provided on | + +### PitchBook Company Updates + +Check which company datasets changed in a window, so a sync only refetches what moved + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook company ID, e.g. 10618-03. Use PitchBook Search to resolve a name to an ID. | +| `sinceDate` | string | No | Window to report changes over, carrying its operator in the value: >YYYY-MM-DD for after a date, <YYYY-MM-DD for before one, or YYYY-MM-DD^YYYY-MM-DD for a range. Use this or trailingRange. | +| `trailingRange` | number | No | Report changes over the last N days. Use this or sinceDate. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `updates` | json | Map of dataset name to whether it changed in the window. Keys are PitchBook dataset names, so read it as a plain object. | + +### PitchBook Patent Search + +Search the patents held by a company by status, filing and publication date, authority, and CPC classification + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook company ID, e.g. 10618-03. Use PitchBook Search to resolve a name to an ID. | +| `status` | string | No | Patent status: Active, Pending, or Inactive. Separate multiple values with a comma. | +| `publicationDate` | string | No | Publication date filter. Use >YYYY-MM-DD, <YYYY-MM-DD, or YYYY-MM-DD^YYYY-MM-DD for a range. | +| `firstFilingDate` | string | No | First filing date filter. Use >YYYY-MM-DD, <YYYY-MM-DD, or YYYY-MM-DD^YYYY-MM-DD for a range. | +| `filingAuthorityLocation` | string | No | Filing authority location, e.g. EP or US. Separate multiple values with a comma. | +| `cpcSectionCode` | string | No | CPC section code. Separate multiple values with a comma. | +| `cpcClassCode` | string | No | CPC class code. Separate multiple values with a comma. | +| `page` | number | No | Page of results to return, starting at 1 | +| `perPage` | number | No | How many results to return per page | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `companyId` | string | PitchBook company ID | +| `stats` | object | Summary statistics for the response | +| ↳ `total` | number | Total number of matching results | +| ↳ `perPage` | number | Results returned per page | +| ↳ `page` | number | Current page number | +| ↳ `lastPage` | number | Number of the last available page | +| `items` | array | Records returned | +| ↳ `patentId` | string | Patent ID | +| ↳ `patentTitle` | string | Patent title | +| ↳ `status` | string | Status | +| ↳ `publicationDate` | string | Publication date \(YYYY-MM-DD\) | +| ↳ `firstFilingDate` | string | First filing date \(YYYY-MM-DD\) | +| ↳ `expirationDate` | string | Expiration date \(YYYY-MM-DD\) | +| ↳ `filingAuthorityLocation` | string | Filing authority location | +| ↳ `cpcSection` | object | CPC section | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `cpcClass` | object | CPC class | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `cpcSubclass` | object | CPC subclass | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | + +### PitchBook Patent Detail + +Retrieve the full record for a single patent: title, status, dates, assignees, inventors, citations, and claim counts + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | Patent ID, e.g. EP-3167426-B1. Patent IDs come from a patent search. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `patentId` | string | Patent ID | +| `patentTitle` | string | Patent title | +| `status` | string | Status | +| `publicationDate` | string | Publication date \(YYYY-MM-DD\) | +| `firstFilingDate` | string | First filing date \(YYYY-MM-DD\) | +| `expirationDate` | json | Expiration date \(YYYY-MM-DD\) | +| `filingAuthorityLocation` | string | Filing authority location | +| `cpcSection` | object | CPC section | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `cpcClass` | object | CPC class | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `cpcSubclass` | object | CPC subclass | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `currentAssigneeNames` | array | Current assignees | +| `originalAssigneeNames` | array | Original assignees | +| `mostRecentLegalStatus` | string | Most recent legal status | +| `mostRecentLegalStatusDate` | string | Date of the most recent legal status \(YYYY-MM-DD\) | +| `applicationDate` | string | Application date \(YYYY-MM-DD\) | +| `grantDate` | string | Grant date \(YYYY-MM-DD\) | +| `familyId` | string | Patent family ID | +| `inventors` | array | Named inventors | +| `documentForwardCitations` | number | Number of forward citations | +| `documentBackwardCitations` | number | Number of backward citations | +| `countOfClaims` | number | Number of claims | +| `countOfIndependentClaims` | number | Number of independent claims | +| `patentDownloadUrl` | string | Link to download the patent document | + +### PitchBook Deal Search + +Search PitchBook for deals by company, investor, deal type, size, date, and valuation + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `companyNames` | string | No | Comma-separated company names, PitchBook IDs, websites, or tickers | +| `investorNames` | string | No | Comma-separated investor names, PitchBook IDs, websites, or tickers | +| `keywords` | string | No | Keywords associated with the companies involved | +| `country` | string | No | Country of the companies involved \(e.g. USA\) | +| `locationType` | string | No | Restrict location matching to HQ_ONLY, NON_HQ_ONLY, or ANY | +| `industry` | string | No | PitchBook industry code of the companies involved | +| `verticals` | string | No | PitchBook vertical code of the companies involved | +| `dealType` | string | No | PitchBook deal type code \(e.g. evc for early-stage VC\) | +| `dealStatus` | string | No | Deal status code, distinguishing completed, failed, and upcoming deals | +| `dealSize` | string | No | Deal size in millions. Use >100, <100, or 10^100 for a range | +| `dealDate` | string | No | Deal date filter. Use >YYYY-MM-DD, <YYYY-MM-DD, or YYYY-MM-DD^YYYY-MM-DD for a range | +| `postValuation` | string | No | Post-money valuation in millions. Use >100, <100, or 10^100 for a range | +| `revenue` | string | No | Revenue of the companies involved in millions. Use >100, <100, or 10^100 for a range | +| `filterCurrency` | string | No | ISO currency code the monetary filters on this search are expressed in, e.g. setting EUR means dealSize is read as millions of euros. Distinct from `currency`, which converts the values PitchBook returns. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | +| `page` | number | No | Page of results to return, starting at 1 | +| `perPage` | number | No | How many results to return per page | +| `additionalFilters` | json | No | Any other documented search filter, as a JSON object of query parameter names to values \(e.g. \{"emergingSpaces": "AGTECH"\}\). A dedicated field always wins over the same key set here. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `stats` | object | Paging envelope for the result set | +| ↳ `total` | number | Total number of matching results | +| ↳ `perPage` | number | Results returned per page | +| ↳ `page` | number | Current page number | +| ↳ `lastPage` | number | Number of the last available page | +| `items` | array | Deals matching the search criteria | +| ↳ `dealId` | string | PitchBook deal ID | +| ↳ `companyId` | string | PitchBook ID of the company in the deal | +| ↳ `companyName` | string | Name of the company in the deal | + +### PitchBook Deal Bio + +Retrieve the summary of a deal: company, date, size, status, type, and which detail datasets are available for it + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook deal ID, e.g. 52721-65T. Deal IDs end in T and come from a deal search or a company deals lookup. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `dealId` | string | PitchBook deal ID | +| `dealNumber` | number | Sequence of this deal in the company financing history | +| `companyId` | string | PitchBook ID of the company in the deal | +| `companyName` | string | Name of the company in the deal | +| `dealAnnouncedDate` | string | Date the deal was announced \(YYYY-MM-DD\) | +| `dealDate` | string | Date the deal closed \(YYYY-MM-DD\) | +| `dealSize` | object | Size of the deal | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `dealSizeStatus` | string | Whether the deal size is actual or estimated | +| `dealStatus` | object | Status of the deal, such as Completed | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `dealType1` | object | Primary deal type | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `dealType2` | object | Secondary deal type, such as the round letter | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `dealType3` | object | Tertiary deal type | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `dealClass` | object | Deal class, such as Venture Capital | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `valuationAvailable` | boolean | Whether valuation data exists for this deal | +| `capTableAvailable` | boolean | Whether cap table history exists for this deal | +| `trancheInfoAvailable` | boolean | Whether tranche information exists for this deal | +| `debtLenderInfoAvailable` | boolean | Whether debt and lender information exists for this deal | + +### PitchBook Deal Detailed + +Retrieve the full detail of a deal: synopsis, percent acquired, round, invested capital, ownership, debt, and stock split + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook deal ID, e.g. 52721-65T. Deal IDs end in T and come from a deal search or a company deals lookup. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `dealId` | string | PitchBook deal ID | +| `dealNumber` | number | Sequence of this deal in the company financing history | +| `companyId` | string | PitchBook ID of the company in the deal | +| `companyName` | string | Name of the company in the deal | +| `dealDate` | string | Date the deal closed \(YYYY-MM-DD\) | +| `dealSize` | object | Size of the deal | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `dealSizeStatus` | string | Whether the deal size is actual or estimated | +| `dealStatus` | object | Status of the deal, such as Completed | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `percentAcquired` | number | Percentage of the company acquired in the deal | +| `raisedToDate` | object | Total the company had raised as of this deal | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `vcRound` | string | Venture round label, such as 1st Round | +| `vcRoundUpDownFlat` | string | Whether the round was up, down, or flat versus the previous one | +| `totalInvestedCapital` | object | Total capital invested in the deal | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `investorOwnership` | number | Percentage of the company owned by investors after the deal | +| `stockSplit` | string | Stock split applied at the deal, such as 1:1 | +| `dealType1` | object | Primary deal type | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `dealType2` | object | Secondary deal type, such as the round letter | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `dealType3` | object | Tertiary deal type | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `dealClass` | object | Deal class, such as Venture Capital | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `dealSynopsis` | string | Narrative summary of the deal | +| `totalInvestedEquity` | object | Total equity invested in the deal | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `debtType1` | object | Primary debt type raised in the deal | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `debtType2` | object | Secondary debt type raised in the deal | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `debtType3` | object | Tertiary debt type raised in the deal | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `debtAmount1` | object | Amount of the primary debt type | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `debtAmount2` | object | Amount of the secondary debt type | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `debtAmount3` | object | Amount of the tertiary debt type | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `debtRaisedInRound` | object | Total debt raised in the round | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `contingentPayout` | object | Contingent payout attached to the deal | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `valuationAvailable` | boolean | Whether valuation data exists for this deal | +| `capTableAvailable` | boolean | Whether cap table history exists for this deal | +| `trancheInfoAvailable` | boolean | Whether tranche information exists for this deal | +| `debtLenderInfoAvailable` | boolean | Whether debt and lender information exists for this deal | + +### PitchBook Deal Valuation + +Retrieve the pre-money and post-money valuation recorded for a deal + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook deal ID, e.g. 52721-65T. Deal IDs end in T and come from a deal search or a company deals lookup. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `dealId` | string | PitchBook deal ID | +| `dealNumber` | number | Sequence of this deal in the company financing history | +| `companyId` | string | PitchBook ID of the company in the deal | +| `companyName` | string | Name of the company in the deal | +| `preValuation` | object | Pre-money valuation | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `postValuation` | object | Post-money valuation | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `postValuationStatus` | string | Whether the post-money valuation is actual or estimated | + +### PitchBook Deal Multiples + +Retrieve the valuation multiples for a deal against revenue, EBITDA, EBIT, cash flow, and net income + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook deal ID, e.g. 52721-65T. Deal IDs end in T. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `dealId` | string | PitchBook deal ID | +| `dealNumber` | number | Sequence of the deal in the company financing history | +| `companyId` | string | PitchBook company ID | +| `companyName` | string | Company name | +| `dealSizeToCashFlow` | number | Deal size to cash flow | +| `dealSizeToEBIT` | number | Deal size to EBIT | +| `dealSizeToEBITDA` | number | Deal size to EBITDA | +| `dealSizeToNetIncome` | json | Deal size to net income | +| `dealSizeToRevenue` | number | Deal size to revenue | +| `debtRaisedInRoundToEBITDA` | json | Debt raised in round to EBITDA | +| `debtRaisedInRoundToEquity` | json | Debt raised in round to equity | +| `impliedEvToCashFlow` | number | Implied EV to cash flow | +| `impliedEvToEBIT` | number | Implied EV to EBIT | +| `impliedEvToEBITDA` | number | Implied EV to EBITDA | +| `impliedEvToNetIncome` | json | Implied EV to net income | +| `impliedEvToRevenue` | number | Implied EV to revenue | +| `valuationToCashFlow` | number | Valuation to cash flow | +| `valuationToEBIT` | number | Valuation to EBIT | +| `valuationToEBITDA` | number | Valuation to EBITDA | +| `valuationToNetIncome` | json | Valuation to net income | +| `valuationToRevenue` | number | Valuation to revenue | + +### PitchBook Deal Investors + +Retrieve the investors, sellers, and exiting investors on a deal, including who led it + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook deal ID, e.g. 52721-65T. Deal IDs end in T and come from a deal search or a company deals lookup. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `dealId` | string | PitchBook deal ID | +| `companyId` | string | PitchBook ID of the company in the deal | +| `companyName` | string | Name of the company in the deal | +| `investors` | array | Investors participating in the deal | +| ↳ `investorId` | string | PitchBook investor ID | +| ↳ `investorName` | string | Investor name | +| ↳ `investmentStatus` | string | Whether the investor is new or following on | +| ↳ `leadSoleInvestor` | boolean | Whether the investor led or solely funded the round | +| ↳ `leadPartnerId` | string | PitchBook person ID of the lead partner | +| ↳ `leadPartnerName` | string | Name of the lead partner | +| ↳ `investorFunds` | array | Funds the investor deployed into the deal | +| ↳ `fundId` | string | PitchBook fund ID | +| ↳ `fundName` | string | Fund name | +| ↳ `investmentAmount` | object | Amount this investor put into the deal | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `formOfPayment` | object | How the investment was paid | +| ↳ `code` | string | Payment form code | +| ↳ `description` | string | Payment form label | +| `sellers` | array | Parties selling in the deal | +| `exiters` | array | Investors exiting through the deal | + +### PitchBook Deal Stock Info + +Retrieve the share terms of a deal: price per share, shares acquired, and the preference, dividend, and voting rights attached + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook deal ID, e.g. 52721-65T. Deal IDs end in T. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `dealId` | string | PitchBook deal ID | +| `dealNumber` | number | Sequence of the deal in the company financing history | +| `companyId` | string | PitchBook company ID | +| `companyName` | string | Company name | +| `series` | string | Stock series | +| `pricePerShare` | object | Price per share | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `stockType` | json | Type of stock | +| `numberOfSharesAcquired` | number | Shares acquired | +| `sharesSought` | number | Shares sought | +| `conversionRatio` | string | Conversion ratio | +| `liquidationPreferences` | string | Liquidation preference terms | +| `liquidationParticipating` | string | Whether the preference participates | +| `dividendRights` | string | Dividend rights terms | +| `cumulativeness` | string | Whether dividends are cumulative | +| `antiDilutionProvisions` | string | Anti-dilution provisions | +| `redemptionRights` | json | Redemption rights terms | +| `boardVotingRights` | string | Board voting rights terms | +| `generalVotingRights` | string | General voting rights terms | + +### PitchBook Deal Cap Table History + +Retrieve the cap table as of a deal, one row per stock series with its terms and ownership + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook deal ID, e.g. 52721-65T. Deal IDs end in T. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `capTable` | array | Stock series on the cap table as of the deal | +| ↳ `dealId` | string | PitchBook deal ID | +| ↳ `dealNumber` | number | Sequence of the deal in the company financing history | +| ↳ `companyId` | string | PitchBook company ID | +| ↳ `companyName` | string | Company name | +| ↳ `stockSeries` | string | Stock series | +| ↳ `numberOfSharesAuthorized` | number | Shares authorized | +| ↳ `parValue` | object | Par value per share | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `dividendRate` | number | Dividend rate | +| ↳ `dividendAmount` | json | Dividend amount | +| ↳ `originalIssuePrice` | object | Original issue price per share | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `liquidationPrice` | object | Liquidation price per share | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `liquidationPreferenceMultiple` | number | Liquidation preference multiple | +| ↳ `conversionPrice` | object | Conversion price per share | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `percentOwned` | number | Percentage owned | + +### PitchBook Deal Tranche Info + +Retrieve the tranches a deal was funded in, with each tranche date, size, and investors + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook deal ID, e.g. 52721-65T. Deal IDs end in T. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `dealId` | string | PitchBook deal ID | +| `dealNumber` | number | Sequence of the deal in the company financing history | +| `company` | object | Company the record belongs to | +| ↳ `id` | string | PitchBook person ID | +| ↳ `name` | string | Name | +| `tranches` | array | Tranches making up the deal | +| ↳ `trancheSize` | object | Size of the tranche | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `currency` | string | Currency of amount | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `trancheSizeStatus` | string | Whether the tranche size is actual or estimated | +| ↳ `trancheDate` | string | Date of the tranche \(YYYY-MM-DD\) | +| ↳ `financingType` | object | Type of financing | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| ↳ `stockType` | object | Type of stock | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| ↳ `stockSeriesType` | string | Type of the stock series | +| ↳ `conversionStatus` | json | Conversion status | +| ↳ `conversionDate` | json | Conversion date \(YYYY-MM-DD\) | +| ↳ `investor` | object | Investor on the record | +| ↳ `name` | string | Name | +| ↳ `id` | string | PitchBook person ID | +| ↳ `investor2` | object | Second investor on the record | +| ↳ `id` | string | PitchBook person ID | +| ↳ `name` | string | Name | +| ↳ `investor3` | object | Third investor on the record | +| ↳ `id` | string | PitchBook person ID | +| ↳ `name` | string | Name | + +### PitchBook Deal Debt and Lenders + +Retrieve the debt raised in a deal and the lenders behind it, with rate, maturity, seniority, and covenant terms + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook deal ID, e.g. 52721-65T. Deal IDs end in T. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `dealId` | string | PitchBook deal ID | +| `dealNumber` | number | Sequence of the deal in the company financing history | +| `company` | object | Company the record belongs to | +| ↳ `id` | string | PitchBook person ID | +| ↳ `name` | string | Name | +| `debts` | array | Debt instruments in the deal | +| ↳ `debtSize` | json | Size of the debt instrument | +| ↳ `paymentInKind` | json | Whether interest is paid in kind | +| ↳ `debtType` | object | Type of debt | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `seniority` | json | Seniority of the debt | +| ↳ `security` | json | Security backing the debt | +| ↳ `subordination` | json | Subordination terms | +| ↳ `term` | json | Term of the debt | +| ↳ `additionalDebtCharacteristics` | object | Other characteristics of the debt | +| ↳ `unitranche` | boolean | Whether the debt is unitranche | +| ↳ `syndicated` | boolean | Whether the debt is syndicated | +| ↳ `mezzanine` | boolean | Whether the debt is mezzanine | +| ↳ `covLite` | boolean | Whether the debt is covenant-lite | +| ↳ `warrants` | boolean | Whether warrants are attached | +| ↳ `convertible` | boolean | Whether the instrument is convertible | +| ↳ `rate` | json | Interest rate | +| ↳ `maturityDate` | json | Maturity date \(YYYY-MM-DD\) | +| ↳ `spreadInterestRate` | json | Spread over the reference interest rate | +| ↳ `lenders` | array | Lenders on the debt | +| ↳ `lenderId` | string | PitchBook ID of the lender | +| ↳ `lenderName` | string | Name of the lender | +| ↳ `firmType` | string | Type of the associated firm | +| ↳ `serviceProviderType` | object | Service provider type | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `lenderSize` | json | Amount provided by the lender | + +### PitchBook Deal Service Providers + +Retrieve the service providers that worked on a deal and which party each represented + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook deal ID, e.g. 52721-65T. Deal IDs end in T. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `serviceProviders` | array | Service providers that worked on the deal | +| ↳ `dealId` | string | PitchBook deal ID | +| ↳ `companyId` | string | PitchBook company ID | +| ↳ `companyName` | string | Company name | +| ↳ `serviceProviderId` | string | PitchBook service provider ID | +| ↳ `serviceProviderName` | string | Service provider name | +| ↳ `serviceProviderTypes` | array | Types the service provider is classified as | +| ↳ `type` | object | Type as a code and description pair | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| ↳ `primary` | boolean | Whether this is the primary entry | +| ↳ `serviceProvided` | object | Service provided, as a code and description pair | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `serviceProvidedToId` | string | PitchBook ID of the party the service was provided to | +| ↳ `serviceProvidedToName` | string | Name of the party the service was provided to | +| ↳ `leadPartnerId` | json | PitchBook person ID of the lead partner | +| ↳ `leadPartnerName` | json | Name of the lead partner | + +### PitchBook Deal Updates + +Check which deal datasets changed in a window, so a sync only refetches what moved + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook deal ID, e.g. 52721-65T. Deal IDs end in T. | +| `sinceDate` | string | No | Window to report changes over, carrying its operator in the value: >YYYY-MM-DD for after a date, <YYYY-MM-DD for before one, or YYYY-MM-DD^YYYY-MM-DD for a range. Use this or trailingRange. | +| `trailingRange` | number | No | Report changes over the last N days. Use this or sinceDate. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `updates` | json | Map of dataset name to whether it changed in the window. Keys are PitchBook dataset names, so read it as a plain object. | + +### PitchBook Investor Search + +Search PitchBook for investors by type, location, assets under management, fund profile, and deal activity + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `investorNames` | string | No | Comma-separated investor names, PitchBook IDs, websites, or tickers | +| `investorType` | string | No | PitchBook investor type code \(e.g. LP_BI, LP_E\) | +| `city` | string | No | City the investor is located in | +| `stateProvince` | string | No | State or province the investor is located in | +| `country` | string | No | Country the investor is located in \(e.g. USA\) | +| `locationType` | string | No | Restrict location matching to HQ_ONLY, NON_HQ_ONLY, or ANY | +| `aum` | string | No | Assets under management in millions. Use >1000, <1000, or 100^1000 for a range | +| `dryPowder` | string | No | Dry powder in millions. Use >500, <500, or 1^500 for a range | +| `fundType` | string | No | PitchBook fund type code of the investor funds | +| `fundSize` | string | No | Fund size in millions. Use >500, <500, or 1^500 for a range | +| `dealType` | string | No | PitchBook deal type code the investor has participated in | +| `dealDate` | string | No | Deal date filter. Use >YYYY-MM-DD, <YYYY-MM-DD, or YYYY-MM-DD^YYYY-MM-DD for a range | +| `dealSize` | string | No | Deal size in millions. Use >100, <100, or 10^100 for a range | +| `preferredDealTypes` | string | No | Preferred deal type codes the investor targets | +| `industryPreferences` | string | No | Preferred industry codes the investor targets | +| `geographicalPreferences` | string | No | Preferred geography codes the investor targets | +| `filterCurrency` | string | No | ISO currency code the monetary filters on this search are expressed in, e.g. setting EUR means dealSize is read as millions of euros. Distinct from `currency`, which converts the values PitchBook returns. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | +| `page` | number | No | Page of results to return, starting at 1 | +| `perPage` | number | No | How many results to return per page | +| `additionalFilters` | json | No | Any other documented search filter, as a JSON object of query parameter names to values \(e.g. \{"emergingSpaces": "AGTECH"\}\). A dedicated field always wins over the same key set here. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `stats` | object | Paging envelope for the result set | +| ↳ `total` | number | Total number of matching results | +| ↳ `perPage` | number | Results returned per page | +| ↳ `page` | number | Current page number | +| ↳ `lastPage` | number | Number of the last available page | +| `items` | array | Investors matching the search criteria | +| ↳ `investorId` | string | PitchBook investor ID | +| ↳ `investorName` | string | Investor name | +| ↳ `website` | string | Investor website | + +### PitchBook Investor Bio + +Retrieve the core profile of an investor: names, description, HQ, type, AUM, dry powder, and headcount + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook investor ID, e.g. 58781-35. Use PitchBook Search to resolve a name to an ID. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `investorId` | string | PitchBook investor ID | +| `investorName` | object | The names the investor is known by | +| ↳ `formalName` | string | Formal name | +| ↳ `alsoKnownAs` | string | Also-known-as name | +| ↳ `legalName` | string | Registered legal name | +| ↳ `formerlyKnownAs` | string | Previous name | +| `hqLocation` | object | Headquarters location | +| ↳ `city` | string | City | +| ↳ `stateProvince` | string | State or province | +| ↳ `postCode` | string | Postal code | +| ↳ `country` | string | Country | +| `description` | object | Investor description in brief and full form | +| ↳ `brief` | string | Short description | +| ↳ `full` | string | Full description | +| `investorStatus` | object | Whether the investor is actively investing | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `investorType` | array | Types the investor is classified as, one flagged primary | +| ↳ `type` | object | Investor type | +| ↳ `code` | string | Investor type code | +| ↳ `description` | string | Investor type label | +| ↳ `primary` | boolean | Whether this is the primary type | +| `assetsUnderManagement` | object | Assets under management | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `dryPowder` | object | Uncalled capital available to deploy | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `yearFounded` | number | Year the investor was founded | +| `website` | string | Investor website | +| `countInvestmentProfessionals` | number | Number of investment professionals on staff | +| `tradeAssociations` | array | Trade associations the investor belongs to | + +### PitchBook Investor Investments + +Retrieve every investment an investor has made, active and exited, with the deals that opened and closed each position + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook investor ID, e.g. 58781-35. Use PitchBook Search to resolve a name to an ID. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `investments` | array | Investments the investor has made, active and exited | +| ↳ `investorId` | string | PitchBook investor ID | +| ↳ `companyId` | string | PitchBook ID of the portfolio company | +| ↳ `companyName` | string | Name of the portfolio company | +| ↳ `investorStatus` | string | Whether the investor is a current or former holder | +| ↳ `investmentDate` | string | Date the position was opened \(YYYY-MM-DD\) | +| ↳ `investmentDealId` | string | PitchBook deal ID of the investment | +| ↳ `exitDate` | string | Date the position was exited \(YYYY-MM-DD\) | +| ↳ `exitDealId` | string | PitchBook deal ID of the exit | + +### PitchBook Investor Active Investments + +Retrieve only the positions an investor still holds + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook investor ID, e.g. 58781-35. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `activeInvestments` | array | Positions the investor still holds | +| ↳ `investorId` | string | PitchBook investor ID | +| ↳ `companyId` | string | PitchBook company ID | +| ↳ `companyName` | string | Company name | +| ↳ `investorSince` | string | Date the investor first invested \(YYYY-MM-DD\) | +| ↳ `investmentDealId` | string | PitchBook deal ID of the investment | +| ↳ `investmentDate` | string | Date the position was opened \(YYYY-MM-DD\) | + +### PitchBook Investor Funds + +Retrieve the funds an investor manages, with open and closed counts and the min, median, and max fund size + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook investor ID, e.g. 58781-35. Use PitchBook Search to resolve a name to an ID. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `investorId` | string | PitchBook investor ID | +| `stats` | object | Counts of open and closed funds | +| ↳ `totalFundsOpen` | number | Number of open funds | +| ↳ `totalFundsClosed` | number | Number of closed funds | +| `minFundSize` | object | Smallest fund raised | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `medianFundSize` | object | Median fund size | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `maxFundSize` | object | Largest fund raised | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `fundInfo` | array | Funds the investor manages | +| ↳ `fundId` | string | PitchBook fund ID | +| ↳ `fundName` | string | Fund name | +| ↳ `fundType` | object | Type of the fund | +| ↳ `code` | string | Fund type code | +| ↳ `description` | string | Fund type label | + +### PitchBook Investor Last Closed Fund + +Retrieve the most recently closed fund raised by an investor, with its size, type, and vintage + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook investor ID, e.g. 58781-35. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `investorId` | string | PitchBook investor ID | +| `fundId` | string | PitchBook fund ID | +| `fundName` | string | Fund name | +| `fundVintage` | number | Vintage year of the fund | +| `fundSize` | object | Capital raised by the fund | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `fundType` | object | Fund type | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `fundCloseDate` | string | Date the fund closed \(YYYY-MM-DD\) | +| `fundOpenDate` | json | Date the fund opened \(YYYY-MM-DD\) | + +### PitchBook Investor Preferences + +Retrieve what an investor targets: check size, deal size, valuation, revenue, geography, industry, and deal type preferences + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook investor ID, e.g. 58781-35. Use PitchBook Search to resolve a name to an ID. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `investorId` | string | PitchBook investor ID | +| `investorName` | string | Investor name | +| `preferredInvestmentAmount` | object | Preferred check size, as a min and max monetary value | +| ↳ `min` | json | Minimum, as a PitchBook monetary value | +| ↳ `max` | json | Maximum, as a PitchBook monetary value | +| `preferredDealSize` | object | Preferred total deal size, as a min and max monetary value | +| ↳ `min` | json | Minimum, as a PitchBook monetary value | +| ↳ `max` | json | Maximum, as a PitchBook monetary value | +| `preferredCompanyValuation` | object | Preferred company valuation, as a min and max monetary value | +| ↳ `min` | json | Minimum, as a PitchBook monetary value | +| ↳ `max` | json | Maximum, as a PitchBook monetary value | +| `preferredEbitda` | object | Preferred EBITDA, as a min and max monetary value | +| ↳ `min` | json | Minimum, as a PitchBook monetary value | +| ↳ `max` | json | Maximum, as a PitchBook monetary value | +| `preferredEbit` | object | Preferred EBIT, as a min and max monetary value | +| ↳ `min` | json | Minimum, as a PitchBook monetary value | +| ↳ `max` | json | Maximum, as a PitchBook monetary value | +| `preferredRevenue` | object | Preferred revenue, as a min and max monetary value | +| ↳ `min` | json | Minimum, as a PitchBook monetary value | +| ↳ `max` | json | Maximum, as a PitchBook monetary value | +| `preferredInvestmentHorizon` | object | Preferred holding period in years | +| ↳ `min` | number | Minimum years | +| ↳ `max` | number | Maximum years | +| `geographicalPreferences` | array | Regions the investor targets, from broad group down to state | +| ↳ `regionGroup` | json | Broad region as a code and description pair | +| ↳ `regionSegment` | json | Region segment as a code and description pair | +| ↳ `regionCode` | json | Country as a code and description pair | +| ↳ `regionState` | json | State or province as a code and description pair | +| `otherInvestmentPreferences` | array | Other stated preferences, such as preferring a minority stake | +| ↳ `code` | string | Preference code | +| ↳ `description` | string | Preference label | +| `preferredIndustry` | array | Industries the investor targets | +| ↳ `code` | string | Industry code | +| ↳ `description` | string | Industry label | +| `preferredDealTypes` | array | Deal types the investor targets | +| ↳ `code` | string | Deal type code | +| ↳ `description` | string | Deal type label | +| `preferredVerticals` | array | Verticals the investor targets | +| ↳ `code` | string | Vertical code | +| ↳ `description` | string | Vertical label | +| `assetPreferences` | array | Asset classes and subcategories the investor targets | +| ↳ `assetClass` | json | Asset class as a code and description pair | +| ↳ `subcategory` | json | Subcategory as a code and description pair | + +### PitchBook Investor Board Seats + +Retrieve the board seats an investor holds and previously held across its portfolio + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook investor ID, e.g. 58781-35. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `investorId` | string | PitchBook investor ID | +| `current` | array | Current entries | +| ↳ `personId` | string | PitchBook person ID | +| ↳ `personName` | string | Full name of the person | +| ↳ `boardCompanyId` | string | PitchBook ID of the company the seat is on | +| ↳ `boardCompanyName` | string | Name of the company the seat is on | +| ↳ `onBoard` | boolean | Whether the person holds a board seat | +| ↳ `boardStartDate` | string | Date the seat started \(YYYY-MM-DD\) | +| ↳ `boardEndDate` | json | Date the seat ended \(YYYY-MM-DD\) | +| ↳ `role` | string | Role played | +| `former` | array | Former team members | + +### PitchBook Investor General Service Providers + +Retrieve the current and former general service providers engaged by an investor + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook investor ID, e.g. 58781-35. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `investorId` | string | PitchBook investor ID | +| `currentGeneralServices` | array | Current general service relationships | +| ↳ `serviceProviderId` | string | PitchBook service provider ID | +| ↳ `serviceProviderName` | string | Service provider name | +| ↳ `serviceProviderTypes` | array | Types the service provider is classified as | +| ↳ `primary` | boolean | Whether this is the primary entry | +| ↳ `type` | object | Type as a code and description pair | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| ↳ `serviceProvided` | object | Service provided, as a code and description pair | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| `formerGeneralServices` | array | Former general service relationships | + +### PitchBook Investor Deal Service Providers + +Retrieve the service providers that worked on an investor deals, and what each was hired for + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook investor ID, e.g. 58781-35. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `dealServiceProviders` | array | Service providers engaged on the investor deals | +| ↳ `investorId` | string | PitchBook investor ID | +| ↳ `serviceProviderId` | string | PitchBook service provider ID | +| ↳ `serviceProviderName` | string | Service provider name | +| ↳ `serviceProviderTypes` | array | Types the service provider is classified as | +| ↳ `primary` | boolean | Whether this is the primary entry | +| ↳ `type` | object | Type as a code and description pair | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| ↳ `serviceProvided` | object | Service provided, as a code and description pair | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| ↳ `dealIdServiceProvided` | string | PitchBook deal ID the service was provided on | + +### PitchBook Investor Updates + +Check which investor datasets changed in a window, so a sync only refetches what moved + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook investor ID, e.g. 58781-35. | +| `sinceDate` | string | No | Window to report changes over, carrying its operator in the value: >YYYY-MM-DD for after a date, <YYYY-MM-DD for before one, or YYYY-MM-DD^YYYY-MM-DD for a range. Use this or trailingRange. | +| `trailingRange` | number | No | Report changes over the last N days. Use this or sinceDate. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `updates` | json | Map of dataset name to whether it changed in the window. Keys are PitchBook dataset names, so read it as a plain object. | + +### PitchBook People Search + +Search PitchBook for people by name, employer, position, education, and location + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `personNames` | string | No | Comma-separated person names or PitchBook person IDs | +| `firstName` | string | No | First name of the person | +| `lastName` | string | No | Last name of the person | +| `email` | string | No | Email address of the person | +| `firmNames` | string | No | Comma-separated firm names, PitchBook IDs, websites, or tickers the person is associated with | +| `firmType` | string | No | PitchBook firm type code of the associated firm | +| `positionLevel` | string | No | Comma-separated position level codes \(e.g. CEO, CFO, CIO\) | +| `positionTitle` | string | No | Position title to match \(e.g. Chief Executive Officer\) | +| `department` | string | No | Department code the person works in | +| `university` | string | No | University the person attended | +| `biography` | string | No | Keywords appearing in the person biography | +| `city` | string | No | City the person is located in | +| `country` | string | No | Country the person is located in \(e.g. USA\) | +| `industry` | string | No | PitchBook industry code of the associated firm | +| `verticals` | string | No | PitchBook vertical code of the associated firm | +| `primaryPositionOnly` | boolean | No | Only match the person primary position rather than any position they hold | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | +| `page` | number | No | Page of results to return, starting at 1 | +| `perPage` | number | No | How many results to return per page | +| `additionalFilters` | json | No | Any other documented search filter, as a JSON object of query parameter names to values \(e.g. \{"emergingSpaces": "AGTECH"\}\). A dedicated field always wins over the same key set here. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `stats` | object | Paging envelope for the result set | +| ↳ `total` | number | Total number of matching results | +| ↳ `perPage` | number | Results returned per page | +| ↳ `page` | number | Current page number | +| ↳ `lastPage` | number | Number of the last available page | +| `items` | array | People matching the search criteria | +| ↳ `personId` | string | PitchBook person ID | +| ↳ `personName` | string | Full name of the person | +| ↳ `firmId` | string | PitchBook ID of the firm the person is associated with | + +### PitchBook Person Bio + +Retrieve the profile of a person: name, biography, LinkedIn, primary employer, position, and office + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook person ID, e.g. 53503-66P. Person IDs end in P and come from a people search. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `personId` | string | PitchBook person ID | +| `personName` | object | Parsed name of the person | +| ↳ `full` | string | Full name | +| ↳ `first` | string | First name | +| ↳ `last` | string | Last name | +| ↳ `middle` | string | Middle name | +| ↳ `prefix` | string | Name prefix | +| ↳ `suffix` | string | Name suffix | +| `biography` | string | Biography of the person | +| `linkedInProfileUrl` | string | LinkedIn profile URL | +| `gender` | string | Gender recorded for the person | +| `primaryEntityId` | string | PitchBook ID of the primary employer | +| `primaryEntityName` | string | Name of the primary employer | +| `primaryEntityType` | string | Type of the primary employer, such as COMPANY or INVESTOR | +| `primaryEntityWebsite` | string | Website of the primary employer | +| `primaryPosition` | string | Position the person holds at the primary employer | +| `primaryOffice` | object | Office the person works out of | +| ↳ `location` | string | Office label | +| ↳ `addressLine1` | string | Address line 1 | +| ↳ `addressLine2` | string | Address line 2 | +| ↳ `city` | string | City | +| ↳ `stateProvince` | string | State or province | +| ↳ `postCode` | string | Postal code | +| ↳ `country` | string | Country | +| ↳ `phone` | string | Phone number | +| ↳ `fax` | string | Fax number | +| ↳ `email` | string | Email address | +| ↳ `globalRegion` | string | Global region | +| ↳ `globalSubRegion` | string | Global sub-region | + +### PitchBook Person Contact + +Retrieve the direct contact details on file for a person + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook person ID, e.g. 53503-66P. Person IDs end in P and come from a people search. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `personId` | string | PitchBook person ID | +| `fullName` | string | Full name of the person | +| `phone` | string | Phone number | +| `fax` | string | Fax number | +| `email` | string | Email address | + +### PitchBook Person Education and Work + +Retrieve a person full history: education, company roles, board seats, deal roles, and fund roles + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook person ID, e.g. 53503-66P. Person IDs end in P and come from a people search. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `personId` | string | PitchBook person ID | +| `fullName` | string | Full name of the person | +| `education` | array | Institutions the person attended | +| ↳ `institution` | string | Institution name | +| ↳ `degree` | string | Degree earned | +| ↳ `yearOfGraduation` | number | Graduation year | +| `companyRoles` | array | Positions the person has held at companies | +| ↳ `companyId` | string | PitchBook company ID | +| ↳ `companyName` | string | Company name | +| ↳ `position` | string | Position title | +| ↳ `positionType` | string | Whether the role is an employee or non-employee position | +| ↳ `positionStatus` | string | Whether the position is Current or Former | +| ↳ `positionStart` | string | Date the position started \(YYYY-MM-DD\) | +| ↳ `positionFinish` | string | Date the position ended \(YYYY-MM-DD\) | +| `boardSeats` | array | Board seats the person has held | +| ↳ `boardCompanyId` | string | PitchBook ID of the company | +| ↳ `boardCompanyName` | string | Name of the company | +| ↳ `boardRepresentingId` | string | PitchBook ID of the firm the seat represents | +| ↳ `boardRepresentingName` | string | Name of the firm the seat represents | +| ↳ `positionStatus` | string | Whether the seat is Current or Former | +| ↳ `boardStart` | string | Date the seat started \(YYYY-MM-DD\) | +| ↳ `boardFinish` | string | Date the seat ended \(YYYY-MM-DD\) | +| `currentAdvisoryRoles` | array | Advisory roles the person currently holds | +| `dealRoles` | array | Deals the person worked on and who they represented | +| ↳ `dealId` | string | PitchBook deal ID | +| ↳ `dealDate` | string | Date of the deal \(YYYY-MM-DD\) | +| ↳ `companyId` | string | PitchBook ID of the company in the deal | +| ↳ `companyName` | string | Name of the company in the deal | +| ↳ `representingId` | string | PitchBook ID of the firm the person represented | +| ↳ `representingName` | string | Name of the firm the person represented | +| `fundRoles` | array | Funds the person is associated with | +| ↳ `fundId` | string | PitchBook fund ID | +| ↳ `fundName` | string | Fund name | +| ↳ `investorId` | string | PitchBook ID of the fund manager | +| ↳ `investorName` | string | Name of the fund manager | +| ↳ `representingId` | string | PitchBook ID of the firm the person represented | +| ↳ `representingName` | string | Name of the firm the person represented | + +### PitchBook Fund Search + +Search PitchBook for funds by manager, type, size, vintage, and performance + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `fundNames` | string | No | Comma-separated fund names or PitchBook fund IDs | +| `investorNames` | string | No | Comma-separated names or PitchBook IDs of the fund managers | +| `fundType` | string | No | PitchBook fund type code | +| `fundSize` | string | No | Fund size in millions. Use >500, <500, or 1^5000 for a range | +| `dryPowder` | string | No | Dry powder in millions. Use >500, <500, or 1^500 for a range | +| `vintage` | string | No | Vintage year. Use >2015, <2015, or 2015^2020 for a range | +| `city` | string | No | City the fund is located in | +| `country` | string | No | Country the fund is located in \(e.g. USA\) | +| `irr` | string | No | Internal rate of return as a percentage. Use >20, <20, or 10^20 for a range | +| `tvpi` | string | No | Total value to paid-in multiple. Use >2, <2, or 1^2 for a range | +| `dpi` | string | No | Distributions to paid-in multiple. Use >1, <1, or 1^2 for a range | +| `industryPreferences` | string | No | Preferred industry codes the fund targets | +| `geographicalPreferences` | string | No | Preferred geography codes the fund targets | +| `filterCurrency` | string | No | ISO currency code the monetary filters on this search are expressed in, e.g. setting EUR means dealSize is read as millions of euros. Distinct from `currency`, which converts the values PitchBook returns. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | +| `page` | number | No | Page of results to return, starting at 1 | +| `perPage` | number | No | How many results to return per page | +| `additionalFilters` | json | No | Any other documented search filter, as a JSON object of query parameter names to values \(e.g. \{"emergingSpaces": "AGTECH"\}\). A dedicated field always wins over the same key set here. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `stats` | object | Paging envelope for the result set | +| ↳ `total` | number | Total number of matching results | +| ↳ `perPage` | number | Results returned per page | +| ↳ `page` | number | Current page number | +| ↳ `lastPage` | number | Number of the last available page | +| `items` | array | Funds matching the search criteria | +| ↳ `fundId` | string | PitchBook fund ID | +| ↳ `fundName` | string | Fund name | +| ↳ `investors` | array | Managers of the fund | +| ↳ `investorId` | string | PitchBook investor ID | +| ↳ `investorName` | string | Investor name | + +### PitchBook Fund Bio + +Retrieve the profile of a fund: managers, vintage, status, type, size, target, location, and team + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook fund ID, e.g. 11373-13F. Fund IDs end in F and come from a fund search. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `fundId` | string | PitchBook fund ID | +| `name` | string | Fund name | +| `fundInvestors` | array | Managers of the fund, with where it sits in their fund series | +| ↳ `investorId` | string | PitchBook investor ID | +| ↳ `investorName` | string | Investor name | +| ↳ `fundNo` | number | Position in the manager fund series | +| ↳ `firstFund` | boolean | Whether this is the manager first fund | +| `vintage` | number | Vintage year of the fund | +| `fundStatus` | string | Whether the fund is open or closed | +| `fundType` | string | Type of the fund | +| `fundSize` | object | Capital raised by the fund | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `location` | object | Office the fund is run from | +| ↳ `location` | string | Office label | +| ↳ `addressLine1` | string | Address line 1 | +| ↳ `addressLine2` | string | Address line 2 | +| ↳ `city` | string | City | +| ↳ `stateProvince` | string | State or province | +| ↳ `postCode` | string | Postal code | +| ↳ `country` | string | Country | +| ↳ `phone` | string | Phone number | +| ↳ `fax` | string | Fax number | +| ↳ `email` | string | Email address | +| ↳ `globalRegion` | string | Global region | +| ↳ `globalSubRegion` | string | Global sub-region | +| `fundTeam` | array | People on the fund team | +| ↳ `personId` | string | PitchBook person ID | +| ↳ `personFullName` | string | Full name of the person | +| `openDate` | string | Date the fund opened \(YYYY-MM-DD\) | +| `closeDate` | string | Date the fund closed \(YYYY-MM-DD\) | +| `fundTargetSize` | object | Target raise for the fund, as a min and max monetary value | +| ↳ `min` | json | Minimum, as a PitchBook monetary value | +| ↳ `max` | json | Maximum, as a PitchBook monetary value | +| `sbic` | boolean | Whether the fund is a Small Business Investment Company | +| `returnsInfoAvailable` | array | Which returns datasets are available for the fund | + +### PitchBook Fund Performance + +Retrieve the most recent reported returns for a fund: IRR, DPI, RVPI, TVPI, NAV, and benchmark quartile + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook fund ID, e.g. 11373-13F. Fund IDs end in F and come from a fund search. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `fundId` | string | PitchBook fund ID | +| `fundName` | string | Fund name | +| `asOfQuarter` | number | Quarter the figures are reported as of | +| `asOfYear` | number | Year the figures are reported as of | +| `irr` | number | Internal rate of return, as a percentage | +| `dpi` | number | Distributions to paid-in multiple | +| `rvpi` | number | Residual value to paid-in multiple | +| `tvpi` | number | Total value to paid-in multiple | +| `nav` | number | Net asset value | +| `quartile` | number | Benchmark quartile the fund falls in, 1 being the best | +| `numberOfFundsInBenchmark` | number | How many funds the benchmark is drawn from | + +### PitchBook Fund Benchmark + +Retrieve the peer benchmark for a fund: benchmark IRR, DPI, TVPI, RVPI, and the funds it is drawn from + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook fund ID, e.g. 11373-13F. Fund IDs end in F. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `fundId` | string | PitchBook fund ID | +| `fundName` | string | Fund name | +| `benchmarkFundType` | object | Fund type the benchmark is built from | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `benchmarkFundSize` | object | Fund size bucket the benchmark is built from | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `benchmarkFundLocation` | object | Location the benchmark is built from | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `benchmarkFundVintageYear` | number | Vintage year the benchmark is built from | +| `irrBenchmark` | number | Benchmark IRR | +| `dpiBenchmark` | number | Benchmark DPI | +| `tvpiBenchmark` | number | Benchmark TVPI | +| `rvpiBenchmark` | number | Benchmark RVPI | +| `numberOfFundsInBenchmark` | number | How many funds the benchmark is drawn from | +| `benchmarkFunds` | array | Funds making up the benchmark | +| ↳ `fundId` | string | PitchBook fund ID | +| ↳ `fundName` | string | Fund name | + +### PitchBook Fund Cash Flows + +Retrieve contributed, distributed, and remaining value for a fund as of a specific quarter + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook fund ID, e.g. 11373-13F. Fund IDs end in F. | +| `period` | string | Yes | Reporting quarter to fetch, formatted as quarter then year, e.g. 4Q2018 | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `fundId` | string | PitchBook fund ID | +| `fundName` | string | Fund name | +| `asOfQuarter` | number | Quarter the figures are reported as of | +| `asOfYear` | number | Year the figures are reported as of | +| `contributed` | object | Capital contributed by limited partners | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `percentCalledDown` | number | Percentage of committed capital called down | +| `dryPowder` | object | Uncalled capital available to deploy | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `percentDryPowder` | number | Percentage of committed capital still uncalled | +| `distributed` | object | Capital distributed back to limited partners | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `remainingValue` | object | Remaining value held in the fund | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `distributedRemaining` | object | Distributed plus remaining value | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | + +### PitchBook Fund Investments + +Retrieve every investment a fund has made, active and exited, with the deals that opened and closed each position + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook fund ID, e.g. 11373-13F. Fund IDs end in F. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `fundId` | string | PitchBook fund ID | +| `fundName` | string | Fund name | +| `investments` | array | Investments held | +| ↳ `targetCompanyId` | string | PitchBook ID of the portfolio company | +| ↳ `targetCompanyName` | string | Name of the portfolio company | +| ↳ `investmentStatus` | string | Whether the position is active or exited | +| ↳ `targetCompanyInvestmentDate` | string | Date the position was opened \(YYYY-MM-DD\) | +| ↳ `investmentDealId` | string | PitchBook deal ID of the investment | +| ↳ `targetCompanyExitDate` | string | Date the position was exited \(YYYY-MM-DD\) | +| ↳ `exitDealId` | string | PitchBook deal ID of the exit | + +### PitchBook Fund Active Investments + +Retrieve only the portfolio positions a fund still holds + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook fund ID, e.g. 11373-13F. Fund IDs end in F. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `activeInvestments` | array | Portfolio positions the fund still holds | +| ↳ `fundId` | string | PitchBook fund ID | +| ↳ `targetCompanyId` | string | PitchBook ID of the portfolio company | +| ↳ `targetCompanyName` | string | Name of the portfolio company | +| ↳ `targetCompanyInvestmentDate` | string | Date the position was opened \(YYYY-MM-DD\) | +| ↳ `investmentDealId` | string | PitchBook deal ID of the investment | + +### PitchBook Fund Commitments + +Retrieve the limited partners committed to a fund, with commitment date, size, status, and type + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook fund ID, e.g. 11373-13F. Fund IDs end in F and come from a fund search. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `commitments` | array | Limited partner commitments to the fund | +| ↳ `fundId` | string | PitchBook fund ID | +| ↳ `limitedPartnerId` | string | PitchBook limited partner ID | +| ↳ `limitedPartnerName` | string | Limited partner name | +| ↳ `commitmentDate` | string | Date of the commitment \(YYYY-MM-DD\) | +| ↳ `commitmentSize` | json | Size of the commitment, as a PitchBook monetary value | +| ↳ `commitmentStatus` | json | Status of the commitment, as a code and description pair | +| ↳ `commitmentType` | json | Type of the commitment, as a code and description pair | + +### PitchBook Fund Investment Preferences + +Retrieve what a fund targets: check size, valuation, geography, industry, vertical, and deal type preferences + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook fund ID, e.g. 11373-13F. Fund IDs end in F. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `fundId` | string | PitchBook fund ID | +| `preferredInvestmentAmount` | json | Preferred check size | +| `preferredDealSize` | json | Preferred deal size | +| `preferredCompanyValuation` | json | Preferred company valuation | +| `preferredEbitda` | json | Preferred EBITDA | +| `preferredEbit` | json | Preferred EBIT | +| `preferredRevenue` | json | Preferred revenue | +| `preferredInvestmentHorizon` | json | Preferred holding period in years | +| `geographicalPreferences` | array | Regions targeted | +| ↳ `regionGroup` | object | Broad region as a code and description pair | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `regionSegment` | object | Region segment as a code and description pair | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `regionCode` | object | Country as a code and description pair | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `regionState` | json | State or province as a code and description pair | +| `otherInvestmentPreferences` | array | Other stated preferences | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `preferredIndustry` | array | Industries targeted | +| ↳ `industryCode` | json | Most specific industry classification | +| ↳ `industrySector` | object | Top-level sector | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| ↳ `industryGroup` | object | Industry group within the sector | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| ↳ `primary` | boolean | Whether this is the primary entry | +| `preferredDealTypes` | array | Deal types targeted | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `preferredVerticals` | array | Verticals targeted | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `assetPreferences` | array | Asset classes and subcategories targeted | + +### PitchBook Fund Team + +Retrieve the active and former people on a fund team + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook fund ID, e.g. 11373-13F. Fund IDs end in F. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `fundId` | string | PitchBook fund ID | +| `investorIds` | array | PitchBook IDs of the fund managers | +| `countActiveTeam` | number | Number of active team members | +| `active` | array | Active team members | +| ↳ `id` | string | PitchBook person ID | +| ↳ `name` | string | Name | +| ↳ `title` | string | Title | +| ↳ `infoAvailable` | boolean | Whether a full PitchBook profile is available | +| `former` | array | Former team members | +| ↳ `id` | string | PitchBook person ID | +| ↳ `name` | string | Name | +| ↳ `title` | string | Title | +| ↳ `infoAvailable` | boolean | Whether a full PitchBook profile is available | + +### PitchBook Fund Updates + +Check which fund datasets changed in a window, so a sync only refetches what moved + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook fund ID, e.g. 11373-13F. Fund IDs end in F. | +| `sinceDate` | string | No | Window to report changes over, carrying its operator in the value: >YYYY-MM-DD for after a date, <YYYY-MM-DD for before one, or YYYY-MM-DD^YYYY-MM-DD for a range. Use this or trailingRange. | +| `trailingRange` | number | No | Report changes over the last N days. Use this or sinceDate. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `updates` | json | Map of dataset name to whether it changed in the window. Keys are PitchBook dataset names, so read it as a plain object. | + +### PitchBook Limited Partner Search + +Search PitchBook for limited partners by type, location, assets under management, and commitment activity + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `limitedPartnerNames` | string | No | Comma-separated limited partner names or PitchBook IDs | +| `limitedPartnerType` | string | No | PitchBook limited partner type code | +| `city` | string | No | City the limited partner is located in | +| `stateProvince` | string | No | State or province the limited partner is located in | +| `country` | string | No | Country the limited partner is located in \(e.g. USA\) | +| `locationType` | string | No | Restrict location matching to HQ_ONLY, NON_HQ_ONLY, or ANY | +| `aum` | string | No | Assets under management in millions. Use >1000, <1000, or 100^1000 for a range | +| `numberOfCommitments` | string | No | Number of fund commitments. Use >1000, <1000, or 10^100 for a range | +| `commitmentSize` | string | No | Commitment size in millions. Use >100, <100, or 10^100 for a range | +| `commitmentDate` | string | No | Commitment date filter. Use >YYYY-MM-DD, <YYYY-MM-DD, or YYYY-MM-DD^YYYY-MM-DD for a range | +| `fundType` | string | No | PitchBook fund type code the limited partner commits to | +| `filterCurrency` | string | No | ISO currency code the monetary filters on this search are expressed in, e.g. setting EUR means dealSize is read as millions of euros. Distinct from `currency`, which converts the values PitchBook returns. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | +| `page` | number | No | Page of results to return, starting at 1 | +| `perPage` | number | No | How many results to return per page | +| `additionalFilters` | json | No | Any other documented search filter, as a JSON object of query parameter names to values \(e.g. \{"emergingSpaces": "AGTECH"\}\). A dedicated field always wins over the same key set here. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `stats` | object | Paging envelope for the result set | +| ↳ `total` | number | Total number of matching results | +| ↳ `perPage` | number | Results returned per page | +| ↳ `page` | number | Current page number | +| ↳ `lastPage` | number | Number of the last available page | +| `items` | array | Limited partners matching the search criteria | +| ↳ `limitedPartnerId` | string | PitchBook limited partner ID | +| ↳ `limitedPartnerName` | string | Limited partner name | +| ↳ `website` | string | Limited partner website | + +### PitchBook Limited Partner Bio + +Retrieve the profile of a limited partner: names, description, type, assets under management, and staff + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook limited partner ID, e.g. 58901-50. Use a limited partner search to resolve a name to an ID. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `limitedPartnerId` | string | PitchBook limited partner ID | +| `limitedPartnerName` | object | The names the limited partner is known by | +| ↳ `formalName` | string | Formal name | +| ↳ `alsoKnownAs` | string | Also-known-as name | +| ↳ `legalName` | string | Registered legal name | +| ↳ `formerlyKnownAs` | string | Previous name | +| `description` | string | Description of the limited partner | +| `limitedPartnerTypes` | array | Types the limited partner is classified as, one flagged primary | +| ↳ `type` | object | Limited partner type | +| ↳ `code` | string | Type code | +| ↳ `description` | string | Type label | +| ↳ `primary` | boolean | Whether this is the primary type | +| `assetsUnderManagement` | object | Assets under management | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| `yearFounded` | number | Year the limited partner was founded | +| `website` | string | Limited partner website | +| `managementStaff` | number | Number of management staff | + +### PitchBook Limited Partner Commitments + +Retrieve every fund commitment a limited partner has made, with date, size, status, and the managers behind each fund + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook limited partner ID, e.g. 58901-50. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `commitments` | array | Fund commitments the limited partner has made | +| ↳ `limitedPartnerId` | string | PitchBook limited partner ID | +| ↳ `committedFundId` | string | PitchBook ID of the fund committed to | +| ↳ `committedFundName` | string | Name of the fund committed to | +| ↳ `committedInvestors` | array | Managers of the fund committed to | +| ↳ `committedInvestorName` | string | Name of the fund manager | +| ↳ `committedInvestorId` | string | PitchBook ID of the fund manager | +| ↳ `commitmentDate` | string | Date of the commitment \(YYYY-MM-DD\) | +| ↳ `commitmentSize` | object | Size of the commitment | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `currency` | string | Currency of amount | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `commitmentStatus` | object | Status of the commitment | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| ↳ `commitmentType` | object | Type of the commitment | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | + +### PitchBook Limited Partner Commitment Aggregates + +Retrieve a limited partner commitments rolled up by fund type, both active and all-time + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook limited partner ID, e.g. 58901-50. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `limitedPartnerId` | string | PitchBook limited partner ID | +| `limitedPartnerName` | string | Limited partner name | +| `activeCommitmentsInDebtFunds` | json | Number of active commitments to debt funds | +| `activeCommitmentsInPeFunds` | number | Number of active commitments to PE funds | +| `activeCommitmentsInReFunds` | number | Number of active commitments to real estate funds | +| `activeCommitmentsInVcFunds` | number | Number of active commitments to VC funds | +| `activeCommitmentsInFoFsAnd2nd` | json | Number of active commitments to funds of funds and secondaries | +| `activeCommitmentsInInfrastructure` | json | Number of active commitments to infrastructure funds | +| `activeCommitmentsInEnergyFunds` | json | Number of active commitments to energy funds | +| `activeCommitmentsInOtherFunds` | number | Number of active commitments to other funds | +| `totalActiveCommitments` | number | Number of active commitments | +| `totalCommitmentsInDebtFunds` | json | Number of all commitments to debt funds | +| `totalCommitmentsInPeFunds` | number | Number of all commitments to PE funds | +| `totalCommitmentsInReFunds` | number | Number of all commitments to real estate funds | +| `totalCommitmentsInVcFunds` | number | Number of all commitments to VC funds | +| `totalCommitmentsInFoFsAnd2nd` | json | Number of all commitments to funds of funds and secondaries | +| `totalCommitmentsInInfrastructure` | json | Number of all commitments to infrastructure funds | +| `totalCommitmentsInEnergyFunds` | json | Number of all commitments to energy funds | +| `totalCommitmentsInOtherFunds` | number | Number of all commitments to other funds | +| `totalCommitments` | number | Number of commitments ever made | + +### PitchBook Limited Partner Commitment Preferences + +Retrieve what a limited partner commits to: preferred commitment size, fund types, and geographies + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook limited partner ID, e.g. 58901-50. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `limitedPartnerId` | string | PitchBook limited partner ID | +| `limitedPartnerName` | string | Limited partner name | +| `preferredCommitmentSize` | json | Preferred commitment size | +| `preferredGeography` | array | Regions the limited partner targets | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `preferredFundTypes` | array | Fund types the limited partner targets | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `preferredDirectInvestmentSize` | json | Preferred direct investment size | +| `otherInvestmentPreferences` | array | Other stated preferences | + +### PitchBook Limited Partner Actual Allocations + +Retrieve a limited partner reported asset allocation across cash, equities, fixed income, private equity, real estate, and alternatives + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook limited partner ID, e.g. 58901-50. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `limitedPartnerId` | string | PitchBook limited partner ID | +| `limitedPartnerName` | string | Limited partner name | +| `affiliatedFunds` | number | Number of affiliated funds | +| `affiliatedInvestors` | number | Number of affiliated investors | +| `allocations` | array | Reported asset allocations | +| ↳ `alternativeInvestments` | json | Amount allocated to alternative investments | +| ↳ `alternativeInvestmentsPercent` | json | Percentage of the portfolio allocated to alternative investments | +| ↳ `privateEquity` | object | Amount allocated to private equity | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `privateEquityPercent` | number | Percentage of the portfolio allocated to private equity | +| ↳ `realEstate` | object | Amount allocated to real estate | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `realEstatePercent` | number | Percentage of the portfolio allocated to real estate | +| ↳ `specialOpportunities` | json | Amount allocated to special opportunities | +| ↳ `specialOpportunitiePercent` | json | Percentage of the portfolio allocated to special opportunities | +| ↳ `hedgeFunds` | object | Amount allocated to hedge funds | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `hedgeFundsPercent` | number | Percentage of the portfolio allocated to hedge funds | +| ↳ `equities` | object | Amount allocated to equities | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `equitiesPercent` | number | Percentage of the portfolio allocated to equities | +| ↳ `fixedIncome` | object | Amount allocated to fixed income | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `fixedIncomePercent` | number | Percentage of the portfolio allocated to fixed income | +| ↳ `cash` | object | Amount allocated to cash | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `cashPercent` | number | Percentage of the portfolio allocated to cash | + +### PitchBook Limited Partner Target Allocations + +Retrieve a limited partner target allocation ranges per asset class, in both value and percentage terms + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook limited partner ID, e.g. 58901-50. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `limitedPartnerId` | string | PitchBook limited partner ID | +| `limitedPartnerName` | string | Limited partner name | +| `targetAllocations` | array | Target asset allocations | +| ↳ `policyDescription` | string | Allocation policy description | +| ↳ `alternativesMin` | json | Alternatives min | +| ↳ `alternativesPercentMin` | json | Alternatives percent min | +| ↳ `alternativesMax` | json | Alternatives max | +| ↳ `alternativesPercentMax` | json | Alternatives percent max | +| ↳ `privateEquityMin` | object | Minimum target allocation to private equity | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `privateEquityPercentMin` | number | Minimum target allocation to private equity, as a percentage | +| ↳ `privateEquityMax` | object | Maximum target allocation to private equity | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `privateEquityPercentMax` | number | Maximum target allocation to private equity, as a percentage | +| ↳ `realEstateMin` | object | Minimum target allocation to real estate | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `realEstatePercentMin` | number | Minimum target allocation to real estate, as a percentage | +| ↳ `realEstateMax` | object | Maximum target allocation to real estate | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `realEstatePercentMax` | number | Maximum target allocation to real estate, as a percentage | +| ↳ `specialOpportunitiesMin` | json | Minimum target allocation to special opportunities | +| ↳ `specialOpportunitiesPercentMin` | json | Minimum target allocation to special opportunities, as a percentage | +| ↳ `specialOpportunitiesMax` | json | Maximum target allocation to special opportunities | +| ↳ `specialOpportunitiesPercentMax` | json | Maximum target allocation to special opportunities, as a percentage | +| ↳ `hedgeFundsMin` | json | Minimum target allocation to hedge funds | +| ↳ `hedgeFundsPercentMin` | json | Minimum target allocation to hedge funds, as a percentage | +| ↳ `hedgeFundsMax` | json | Maximum target allocation to hedge funds | +| ↳ `hedgeFundsPercentMax` | json | Maximum target allocation to hedge funds, as a percentage | +| ↳ `equitiesMin` | object | Minimum target allocation to equities | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `equitiesPercentMin` | number | Minimum target allocation to equities, as a percentage | +| ↳ `equitiesMax` | object | Maximum target allocation to equities | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `equitiesPercentMax` | number | Maximum target allocation to equities, as a percentage | +| ↳ `fixedIncomeMin` | object | Minimum target allocation to fixed income | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `fixedIncomePercentMin` | number | Minimum target allocation to fixed income, as a percentage | +| ↳ `fixedIncomeMax` | object | Maximum target allocation to fixed income | +| ↳ `amount` | number | Value in the requested currency | +| ↳ `currency` | string | Currency of amount | +| ↳ `nativeAmount` | number | Value in the currency it was originally reported in | +| ↳ `nativeCurrency` | string | Currency of nativeAmount | +| ↳ `estimated` | boolean | Whether the value is a PitchBook estimate | +| ↳ `fixedIncomePercentMax` | number | Maximum target allocation to fixed income, as a percentage | +| ↳ `cashMin` | json | Minimum target allocation to cash | +| ↳ `cashPercentMin` | json | Minimum target allocation to cash, as a percentage | +| ↳ `cashMax` | json | Maximum target allocation to cash | +| ↳ `cashPercentMax` | json | Maximum target allocation to cash, as a percentage | + +### PitchBook Limited Partner Service Providers + +Retrieve the current and former service providers engaged by a limited partner + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook limited partner ID, e.g. 58901-50. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `limitedPartnerId` | string | PitchBook limited partner ID | +| `currentGeneralServices` | array | Current general service relationships | +| ↳ `serviceProviderId` | string | PitchBook service provider ID | +| ↳ `serviceProviderName` | string | Service provider name | +| ↳ `serviceProviderTypes` | array | Types the service provider is classified as | +| ↳ `primary` | boolean | Whether this is the primary entry | +| ↳ `type` | object | Type as a code and description pair | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| ↳ `serviceProvided` | object | Service provided, as a code and description pair | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| `formerGeneralServices` | array | Former general service relationships | +| ↳ `serviceProviderId` | string | PitchBook service provider ID | +| ↳ `serviceProviderName` | string | Service provider name | +| ↳ `serviceProviderTypes` | array | Types the service provider is classified as | +| ↳ `primary` | boolean | Whether this is the primary entry | +| ↳ `type` | object | Type as a code and description pair | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| ↳ `serviceProvided` | object | Service provided, as a code and description pair | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | + +### PitchBook Limited Partner Updates + +Check which limited partner datasets changed in a window, so a sync only refetches what moved + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook limited partner ID, e.g. 58901-50. | +| `sinceDate` | string | No | Window to report changes over, carrying its operator in the value: >YYYY-MM-DD for after a date, <YYYY-MM-DD for before one, or YYYY-MM-DD^YYYY-MM-DD for a range. Use this or trailingRange. | +| `trailingRange` | number | No | Report changes over the last N days. Use this or sinceDate. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `updates` | json | Map of dataset name to whether it changed in the window. Keys are PitchBook dataset names, so read it as a plain object. | + +### PitchBook Service Provider Search + +Search PitchBook for service providers by type, location, and the deals they have worked on + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `serviceProviderNames` | string | No | Comma-separated service provider names or PitchBook IDs | +| `serviceProviderType` | string | No | PitchBook service provider type code | +| `city` | string | No | City the service provider is located in | +| `stateProvince` | string | No | State or province the service provider is located in | +| `country` | string | No | Country the service provider is located in \(e.g. USA\) | +| `locationType` | string | No | Restrict location matching to HQ_ONLY, NON_HQ_ONLY, or ANY | +| `numberOfDeals` | string | No | Number of deals worked on. Use >50, <50, or 10^50 for a range | +| `dealType` | string | No | PitchBook deal type code of the deals worked on | +| `dealDate` | string | No | Deal date filter. Use >YYYY-MM-DD, <YYYY-MM-DD, or YYYY-MM-DD^YYYY-MM-DD for a range | +| `dealSize` | string | No | Deal size in millions. Use >450, <450, or 10^450 for a range | +| `serviceTypesOnDeal` | string | No | Service type codes provided on the deal | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | +| `page` | number | No | Page of results to return, starting at 1 | +| `perPage` | number | No | How many results to return per page | +| `additionalFilters` | json | No | Any other documented search filter, as a JSON object of query parameter names to values \(e.g. \{"emergingSpaces": "AGTECH"\}\). A dedicated field always wins over the same key set here. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `stats` | object | Paging envelope for the result set | +| ↳ `total` | number | Total number of matching results | +| ↳ `perPage` | number | Results returned per page | +| ↳ `page` | number | Current page number | +| ↳ `lastPage` | number | Number of the last available page | +| `items` | array | Service providers matching the search criteria | +| ↳ `serviceProviderId` | string | PitchBook service provider ID | +| ↳ `serviceProviderName` | string | Service provider name | +| ↳ `website` | string | Service provider website | + +### PitchBook Service Provider Bio + +Retrieve the profile of a service provider: names, types, description, and how many companies, deals, investors, funds, and limited partners it has serviced + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook service provider ID, e.g. 11356-75. Use a service provider search to resolve a name to an ID. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `serviceProviderId` | string | PitchBook service provider ID | +| `serviceProviderName` | object | The names the service provider is known by | +| ↳ `formalName` | string | Formal name | +| ↳ `alsoKnownAs` | string | Also-known-as name | +| ↳ `legalName` | string | Registered legal name | +| ↳ `formerlyKnownAs` | string | Previous name | +| `serviceProviderTypes` | array | Types the service provider is classified as, one flagged primary | +| ↳ `type` | object | Service provider type | +| ↳ `code` | string | Type code | +| ↳ `description` | string | Type label | +| ↳ `primary` | boolean | Whether this is the primary type | +| `description` | string | Description of the service provider | +| `website` | string | Service provider website | +| `employees` | number | Employee count | +| `servicedCompanies` | number | Number of companies serviced | +| `servicedDeals` | number | Number of deals serviced | +| `servicedInvestors` | number | Number of investors serviced | +| `servicedFunds` | number | Number of funds serviced | +| `servicedLimitedPartners` | number | Number of limited partners serviced | + +### PitchBook Serviced Companies + +Retrieve the companies a service provider currently and formerly serves + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook service provider ID, e.g. 11356-75. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `serviceProviderId` | string | PitchBook service provider ID | +| `serviceProviderName` | string | Service provider name | +| `currentGeneralServices` | array | Current general service relationships | +| ↳ `entityId` | string | PitchBook entity ID | +| ↳ `entityName` | string | Entity name | +| ↳ `serviceProvided` | object | Service provided, as a code and description pair | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `formerGeneralServices` | array | Former general service relationships | + +### PitchBook Serviced Deals + +Retrieve the deals a service provider worked on and what it was hired for on each + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook service provider ID, e.g. 11356-75. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `serviceProviderName` | string | Service provider name | +| `servicedDealInfo` | array | Deals the service provider worked on | +| ↳ `companyId` | string | PitchBook company ID | +| ↳ `companyName` | string | Company name | +| ↳ `serviceProvided` | object | Service provided, as a code and description pair | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `dealId` | string | PitchBook deal ID | +| ↳ `dealNumber` | number | Sequence of the deal in the company financing history | +| ↳ `dealDate` | string | Date the deal closed \(YYYY-MM-DD\) | + +### PitchBook Serviced Investors + +Retrieve the investors a service provider currently and formerly serves + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook service provider ID, e.g. 11356-75. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `serviceProviderId` | string | PitchBook service provider ID | +| `serviceProviderName` | string | Service provider name | +| `currentGeneralServices` | array | Current general service relationships | +| ↳ `entityId` | string | PitchBook entity ID | +| ↳ `entityName` | string | Entity name | +| ↳ `serviceProvided` | object | Service provided, as a code and description pair | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | +| `formerGeneralServices` | array | Former general service relationships | + +### PitchBook Serviced Funds + +Retrieve the funds a service provider has worked with and the service provided to each + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook service provider ID, e.g. 11356-75. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `serviceProviderId` | string | PitchBook service provider ID | +| `serviceProviderName` | string | Service provider name | +| `fundServices` | array | Funds the service provider worked with | +| ↳ `fundId` | string | PitchBook fund ID | +| ↳ `fundName` | string | Fund name | +| ↳ `serviceProvided` | object | Service provided, as a code and description pair | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | +| ↳ `servicedEntityType` | object | Type of entity that was serviced | +| ↳ `description` | string | Human-readable label for the code | +| ↳ `code` | string | PitchBook code | + +### PitchBook Serviced Limited Partners + +Retrieve the limited partners a service provider currently and formerly serves + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook service provider ID, e.g. 11356-75. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `serviceProviderId` | string | PitchBook service provider ID | +| `serviceProviderName` | string | Service provider name | +| `currentGeneralServices` | array | Current general service relationships | +| `formerGeneralServices` | array | Former general service relationships | +| ↳ `entityId` | string | PitchBook entity ID | +| ↳ `entityName` | string | Entity name | +| ↳ `serviceProvided` | object | Service provided, as a code and description pair | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | + +### PitchBook Service Provider Updates + +Check which service provider datasets changed in a window, so a sync only refetches what moved + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | PitchBook service provider ID, e.g. 11356-75. | +| `sinceDate` | string | No | Window to report changes over, carrying its operator in the value: >YYYY-MM-DD for after a date, <YYYY-MM-DD for before one, or YYYY-MM-DD^YYYY-MM-DD for a range. Use this or trailingRange. | +| `trailingRange` | number | No | Report changes over the last N days. Use this or sinceDate. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `updates` | json | Map of dataset name to whether it changed in the window. Keys are PitchBook dataset names, so read it as a plain object. | + +### PitchBook Credit News Search + +Search PitchBook credit analysis news by author, region, asset class, topic, issuer, lender, sponsor, and date + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `authors` | string | No | Article author name. Separate multiple values with a comma. | +| `regions` | string | No | Region the article covers: United States or Europe. | +| `assetClasses` | string | No | Asset class the article covers. Separate multiple values with a comma. | +| `topics` | string | No | Topic the article covers. Separate multiple values with a comma. | +| `issuer` | string | No | Issuer name. Separate multiple values with a comma. | +| `lender` | string | No | Lender name. Separate multiple values with a comma. | +| `sponsor` | string | No | Sponsor name. Separate multiple values with a comma. | +| `sinceDate` | string | No | Publication date filter. Use >YYYY-MM-DD, <YYYY-MM-DD, or YYYY-MM-DD^YYYY-MM-DD for a range. | +| `page` | number | No | Page of results to return, starting at 1 | +| `perPage` | number | No | How many results to return per page, between 1 and 250. Defaults to 25. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `stats` | object | Summary statistics for the response | +| ↳ `total` | number | Total number of matching results | +| ↳ `perPage` | number | Results returned per page | +| ↳ `page` | number | Current page number | +| ↳ `lastPage` | number | Number of the last available page | +| `items` | array | Records returned | +| ↳ `articleId` | number | Credit news article ID | +| ↳ `title` | string | Title | +| ↳ `authors` | array | Authors of the article | +| ↳ `authorName` | string | Author name | +| ↳ `regions` | array | Geographic regions the article covers | +| ↳ `publishDate` | string | Publication timestamp \(ISO 8601\) | +| ↳ `assetClasses` | array | Asset classes the article covers | +| ↳ `topics` | array | Topics the article covers | +| ↳ `issuer` | object | Issuer the article is about | +| ↳ `pbId` | string | PitchBook entity ID | +| ↳ `name` | string | Name | +| ↳ `lender` | object | Lender the article is about | +| ↳ `pbId` | string | PitchBook entity ID | +| ↳ `name` | string | Name | +| ↳ `sponsor` | object | Sponsor the article is about | +| ↳ `pbId` | string | PitchBook entity ID | +| ↳ `name` | string | Name | + +### PitchBook Most Recent Credit News + +Retrieve the most recently published credit analysis articles and their descriptions, without article bodies + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `page` | number | No | Page of results to return, starting at 1. Increment it to reach older articles. | +| `perPage` | number | No | How many results to return per page, between 1 and 250. Defaults to 25. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `stats` | object | Summary statistics for the response | +| ↳ `total` | number | Total number of matching results | +| ↳ `perPage` | number | Results returned per page | +| ↳ `page` | number | Current page number | +| ↳ `lastPage` | number | Number of the last available page | +| `items` | array | Records returned | +| ↳ `articleId` | number | Credit news article ID | +| ↳ `title` | string | Title | +| ↳ `authors` | array | Authors of the article | +| ↳ `authorName` | string | Author name | +| ↳ `regions` | array | Geographic regions the article covers | +| ↳ `publishDate` | string | Publication timestamp \(ISO 8601\) | +| ↳ `assetClasses` | array | Asset classes the article covers | +| ↳ `topics` | array | Topics the article covers | +| ↳ `issuer` | object | Issuer the article is about | +| ↳ `pbId` | string | PitchBook entity ID | +| ↳ `name` | string | Name | +| ↳ `lender` | object | Lender the article is about | +| ↳ `pbId` | string | PitchBook entity ID | +| ↳ `name` | string | Name | +| ↳ `sponsor` | object | Sponsor the article is about | +| ↳ `pbId` | string | PitchBook entity ID | +| ↳ `name` | string | Name | + +### PitchBook Credit News Article + +Retrieve one credit analysis article in full, including its body text, authors, topics, and the issuer, lender, and sponsor it covers + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pbId` | string | Yes | Credit news article ID, e.g. 1312103. Article IDs come from a credit news search. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `articleId` | number | Credit news article ID | +| `title` | string | Title | +| `authors` | array | Authors of the article | +| ↳ `authorName` | string | Author name | +| `regions` | array | Geographic regions the article covers | +| `publishDate` | string | Publication timestamp \(ISO 8601\) | +| `assetClasses` | array | Asset classes the article covers | +| `topics` | array | Topics the article covers | +| `issuer` | object | Issuer the article is about | +| ↳ `pbId` | string | PitchBook entity ID | +| ↳ `name` | string | Name | +| `lender` | json | Lender the article is about | +| `sponsor` | json | Sponsor the article is about | +| `articleBody` | string | Full text of the article | +| `attachments` | array | Attachments on the article | + +### PitchBook Credit News Bulk + +Retrieve many credit analysis articles in full in a single call, reporting which IDs were found, missing, or duplicated + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `articleIds` | array | Yes | Credit news article IDs to fetch, e.g. \[11041384, 2142401\] | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `stats` | object | Summary statistics for the response | +| ↳ `total` | number | Total number of matching results | +| ↳ `found` | number | Articles that were found | +| ↳ `notFound` | number | Article IDs that were not found | +| ↳ `duplicates` | number | Article IDs that were requested more than once | +| `found` | array | Articles that were found | +| ↳ `articleId` | number | Credit news article ID | +| ↳ `title` | string | Title | +| ↳ `authors` | array | Authors of the article | +| ↳ `authorName` | string | Author name | +| ↳ `regions` | array | Geographic regions the article covers | +| ↳ `publishDate` | string | Publication timestamp \(ISO 8601\) | +| ↳ `assetClasses` | array | Asset classes the article covers | +| ↳ `topics` | array | Topics the article covers | +| ↳ `issuer` | object | Issuer the article is about | +| ↳ `pbId` | string | PitchBook entity ID | +| ↳ `name` | string | Name | +| ↳ `lender` | json | Lender the article is about | +| ↳ `sponsor` | json | Sponsor the article is about | +| ↳ `articleBody` | string | Full text of the article | +| ↳ `attachments` | array | Attachments on the article | +| ↳ `deal` | object | Deal the record belongs to | +| ↳ `dealId` | string | PitchBook deal ID | +| `notFound` | array | Article IDs that were not found | +| `duplicates` | array | Article IDs that were requested more than once | + +### PitchBook Contracts History + +Retrieve the API contracts on the account with their pricing model, term, and credit balances + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `activeContract` | boolean | No | Set true for only active contracts, false for only past ones. Omit to return every contract. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `contracts` | array | Contracts on the account | +| ↳ `contractNumber` | string | Contract identifier | +| ↳ `activeContract` | boolean | Whether the contract is currently active | +| ↳ `pricingModel` | string | Pricing model of the contract | +| ↳ `startDate` | string | Start date \(YYYY-MM-DD\) | +| ↳ `endDate` | string | End date \(YYYY-MM-DD\) | +| ↳ `creditsUsed` | number | Credits consumed | +| ↳ `creditsChanged` | number | Net credits added or removed | +| ↳ `creditsExpired` | number | Credits that expired | +| ↳ `creditsRemaining` | number | Credits still available | +| ↳ `overageUsed` | number | Overage credits consumed | + +### PitchBook Credit History + +Retrieve API credit usage and remaining balance per contract, for up to the last 90 days + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `sinceDate` | string | No | Window to report changes over, carrying its operator in the value: >YYYY-MM-DD for after a date, <YYYY-MM-DD for before one, or YYYY-MM-DD^YYYY-MM-DD for a range. Use this or trailingRange. | +| `trailingRange` | number | No | Report changes over the last N days. Use this or sinceDate. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `credits` | array | Credit usage per contract over the window | +| ↳ `contractNumber` | string | Contract identifier | +| ↳ `activeContract` | boolean | Whether the contract is currently active | +| ↳ `pricingModel` | string | Pricing model of the contract | +| ↳ `creditsUsed` | number | Credits consumed | +| ↳ `creditsChanged` | number | Net credits added or removed | +| ↳ `creditsExpired` | number | Credits that expired | +| ↳ `creditsRemaining` | number | Credits still available | +| ↳ `overageUsed` | number | Overage credits consumed | + +### PitchBook Usage Report + +Retrieve how many API calls were made and how many credits they charged, for up to the last 90 days + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `sinceDate` | string | No | Window to report changes over, carrying its operator in the value: >YYYY-MM-DD for after a date, <YYYY-MM-DD for before one, or YYYY-MM-DD^YYYY-MM-DD for a range. Use this or trailingRange. | +| `trailingRange` | number | No | Report changes over the last N days. Use this or sinceDate. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `stats` | object | Summary statistics for the response | +| ↳ `endpoints` | array | Per-endpoint call breakdown | +| ↳ `totalCountOfCalls` | number | Total number of calls made | +| ↳ `totalChargedCredits` | number | Total credits charged | +| `rawData` | array | Individual call records | + +### PitchBook Cost of Calls + +Retrieve the credit cost of every API endpoint under a given pricing model, for first-time and refresh calls + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `pricingModel` | string | No | Pricing model to price against: SUBSCRIPTION or PAY_PER_CALL | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `costs` | array | Credit cost per endpoint | +| ↳ `group` | string | Endpoint group | +| ↳ `endpoint` | string | Endpoint name | +| ↳ `initialCost` | number | Credit cost of a first-time call | +| ↳ `refreshCost` | number | Credit cost of re-requesting data already pulled | + +### PitchBook Lookup Table Structure + +List the lookup tables backing the search endpoints. Use this to find which table holds the codes a search filter expects. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `tables` | array | Lookup tables available | +| ↳ `tableName` | string | Lookup table name | +| ↳ `tableDescription` | string | What the lookup table contains | + +### PitchBook Lookup Tables + +Retrieve the codes in one or more lookup tables. These are the codes the search filters expect, such as INDUSTRY or VERTICAL. + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `tableNames` | string | Yes | Lookup tables to return, e.g. INDUSTRY or VERTICAL. Separate multiple names with a comma. Use the lookup table structure operation to see what is available. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `items` | array | Records returned | +| ↳ `tableName` | string | Lookup table name | +| ↳ `tableDescription` | string | What the lookup table contains | +| ↳ `codes` | array | Codes in the lookup table | +| ↳ `code` | string | PitchBook code | +| ↳ `description` | string | Human-readable label for the code | + +### PitchBook Sandbox Entities + +List the entities a sandbox API key is allowed to query, so test workflows have real IDs to run against + +#### Input + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `apiKey` | string | Yes | PitchBook API key | +| `entityType` | string | Yes | Entity type to list: COMPANIES, INVESTORS, LIMITED_PARTNERS, SERVICE_PROVIDERS, PEOPLE, DEALS, or FUNDS. The matching array on the response is named after it, so COMPANIES returns a companies array. | +| `currency` | string | No | ISO currency code to convert monetary values into, sent as the X-Currency header \(e.g. USD, EUR, JPY\). Defaults to the currency on the account preferences. | + +#### Output + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `entities` | array | Entities the sandbox key may query. PitchBook names this array after the requested entity type, so it is surfaced under a stable `entities` key rather than the type-specific one. | +| ↳ `companyId` | string | PitchBook ID of the entity, keyed by its own entity type | +| ↳ `companyName` | string | Name of the entity, keyed by its own entity type | +| `entityTypeCounts` | json | Count of available sandbox entities, keyed by entity type | + + diff --git a/apps/docs/content/docs/en/platform/self-hosting/docker.mdx b/apps/docs/content/docs/en/platform/self-hosting/docker.mdx index 1b911191227..0974cfb8e41 100644 --- a/apps/docs/content/docs/en/platform/self-hosting/docker.mdx +++ b/apps/docs/content/docs/en/platform/self-hosting/docker.mdx @@ -10,20 +10,14 @@ import { FAQ } from '@/components/ui/faq' ## Quick Start ```bash -git clone https://github.com/simstudioai/sim.git && cd sim - -cat > .env << EOF -BETTER_AUTH_SECRET=$(openssl rand -hex 32) -ENCRYPTION_KEY=$(openssl rand -hex 32) -INTERNAL_API_SECRET=$(openssl rand -hex 32) -CRON_SECRET=$(openssl rand -hex 32) -EOF - -docker compose -f docker-compose.prod.yml up -d +npx sim-setup ``` Open [http://localhost:3000](http://localhost:3000) +The setup package creates `./sim` with a generated `.env` and the production Compose file, then +starts published container images. Pass `--dir ` to choose another directory. + ## Production Setup ### 1. Configure Environment @@ -150,7 +144,7 @@ docker compose -f docker-compose.prod.yml logs migrations docker compose -f docker-compose.prod.yml logs -f cron # Upgrade: bump SIM_VERSION in .env when pinned, then -bun run sim update +npx sim-setup update ``` /api/auth/oauth2/callback/bitbucket` as its callback URL. Bitbucket fixes +permissions on the consumer instead of narrowing them per authorization request. Enable exactly +Account read, Repositories read/write, Pull requests read/write, and Pipelines read/write +(`account`, `repository`, `repository:write`, `pullrequest`, `pullrequest:write`, `pipeline`, and +`pipeline:write`). Webhook permission is not required for the integration-only release. + ### Services with a different flow | Service | Configuration | Notes | diff --git a/apps/docs/content/docs/en/platform/self-hosting/upgrades.mdx b/apps/docs/content/docs/en/platform/self-hosting/upgrades.mdx index 265d56e53b9..bc5f1c21a39 100644 --- a/apps/docs/content/docs/en/platform/self-hosting/upgrades.mdx +++ b/apps/docs/content/docs/en/platform/self-hosting/upgrades.mdx @@ -142,11 +142,11 @@ kubectl logs -n simstudio deploy/sim-app -c migrations --tail=100 ```bash -bun run sim update +npx sim-setup update docker compose -f docker-compose.prod.yml logs migrations ``` -`bun run sim update` pulls the versions configured by `SIM_VERSION` (or `latest` when it is +`npx sim-setup update` pulls the versions configured by `SIM_VERSION` (or `latest` when it is unset), recreates the changed services, and keeps data volumes. It is equivalent to running `docker compose pull` followed by `docker compose up -d`. diff --git a/apps/sim/app/(landing)/components/features/features.tsx b/apps/sim/app/(landing)/components/features/features.tsx index d7fafca3867..498ab5b2ced 100644 --- a/apps/sim/app/(landing)/components/features/features.tsx +++ b/apps/sim/app/(landing)/components/features/features.tsx @@ -1,4 +1,4 @@ -import { BuildCallout } from '@/app/(landing)/components/features/components/build-callout/build-callout' +import { BuildCallout } from '@/app/(landing)/components/features/components/build-callout' import { FeatureCard } from '@/app/(landing)/components/features/components/feature-card' import { IntegrationsCallout } from '@/app/(landing)/components/features/components/integrations-callout/integrations-callout' import { KnowledgeCallout } from '@/app/(landing)/components/features/components/knowledge-callout/knowledge-callout' diff --git a/apps/sim/app/(landing)/components/landing-preview/components/landing-preview-chat/chat-input.tsx b/apps/sim/app/(landing)/components/landing-preview/components/landing-preview-chat/chat-input.tsx deleted file mode 100644 index 7ce8c3c545f..00000000000 --- a/apps/sim/app/(landing)/components/landing-preview/components/landing-preview-chat/chat-input.tsx +++ /dev/null @@ -1,99 +0,0 @@ -'use client' - -import { useRef } from 'react' -import { ArrowUp, cn, Mic, Paperclip, Slash } from '@sim/emcn' - -interface LandingPreviewChatInputProps { - value: string - onChange?: (value: string) => void - onSubmit: () => void - placeholder: string - /** Locks the field (used while the demo auto-types). */ - readOnly?: boolean - /** Hides the caret (auto-type has no real cursor). */ - caretHidden?: boolean - /** Lifts the field with the home-view shadow (only the initial empty state). */ - shadow?: boolean -} - -const ICON_BUTTON = - 'flex size-[28px] flex-shrink-0 items-center justify-center rounded-full transition-colors hover-hover:bg-[var(--surface-1)]' - -/** - * The canonical Mothership chat input - a faithful copy of the workspace - * `UserInput`: a white, `rounded-[17px]` field with the text area on top and a - * control row beneath (attach + skills on the left, mic + send on the right). - * The send button carries the real `SEND_BUTTON` fills (`#383838` active, - * `#808080` disabled). Shared by the home empty state and the docked chat pane - * so both read identically. - */ -export function LandingPreviewChatInput({ - value, - onChange, - onSubmit, - placeholder, - readOnly = false, - caretHidden = false, - shadow = false, -}: LandingPreviewChatInputProps) { - const textareaRef = useRef(null) - const isEmpty = value.trim().length === 0 - - return ( -
textareaRef.current?.focus()} - className={cn( - 'cursor-text rounded-[17px] border border-[var(--border-1)] bg-[var(--surface-2)] px-2.5 py-2', - shadow && 'shadow-[0_1px_2px_0_rgba(18,18,18,0.05)]' - )} - > -