PIpipeshub-ai
Connector

Resolve a URL, issue key or external ID to a Record ID

Changed on

Turn an external reference into the matching PipesHub record. Accepts a pasted link, a Jira-style issue key, or a bare external system ID from any connected source. Repeat identifiers to batch-resolve up to ten in one call.

The response carries a rendered text view — each match's metadata block followed by a Next: line naming a follow-up call. The structured fields carry the same information for programmatic use.

Accepted identifiers

  • Jira issue URL — https://acme.atlassian.net/browse/PA-1787
  • Jira issue key — PA-1787
  • Confluence page URL — https://acme.atlassian.net/wiki/spaces/SD/pages/450625553/Agent+Loop
  • Google Drive / Docs URL — https://docs.google.com/document/d/1AbC.../edit
  • Slack message link — https://acme.slack.com/archives/C0123/p1720000000000100
  • Bare external system ID — 450625553

When to use this vs. the other record endpoints:

  • This endpoint converts an external reference into an internal Record ID. Reach for it whenever you meet a link or ticket key and need the record behind it.
  • GET /connectors/record/{recordId}/content reads a record you have already identified. It needs an internal Record ID, which is exactly what this endpoint returns.
  • GET /connectors/navigate browses the hierarchy when you have a position in the tree rather than a specific identifier.

Typical flow: call this with the reference, take a match's id from the response, then call GET /connectors/record/{recordId}/content to read the record.

Multiple matches: one identifier can legitimately match more than one record — the same external ID may exist in several connected instances. In that case the response sets ambiguous: true and matches holds every candidate. Present the choice rather than taking the first; connectorName narrows a retry.

Misses are not errors.

Only records the caller can see are returned, and a miss is a 200 with an empty matches array and the input echoed in not_found_identifiers — not a 404. The identifier resolved to nothing or to something the caller may not access; the two are deliberately indistinguishable, because an identifier is caller-supplied and guessable, and confirming existence would leak records across organizations. searched_connectors names what was covered, so a retry with connectorName is often the right next move.

Scope: resolution searches every connector the caller can access, regardless of any source filter used elsewhere.

A connected app with a limit: each match's context_block names nothing outside the limit beside the record. Its External Parent ID reads N/A for a parent the limit leaves out, and a code file's Path: line is left out unless the limit covers the whole app. Linked records, related tables, a deal's orgs and products, and live Jira parent, epic, sub-task and linked-issue lines appear only for records inside the limit. Web URL is kept, though it can contain folder names.

An OAuth token holding connector:read instead of kb:read is accepted too.

get/connectors/record/lookup

Request

  • Base URL
    https://app.pipeshub.com/api/v1
  • URL
    https://app.pipeshub.com/api/v1/connectors/record/lookup
  • Auth
    • HTTP bearer
    • or OAuth 2
      Authorization code: /api/v1/oauth2/authorize
      Client credentials
      Token URL: /api/v1/oauth2/token scopes: kb:read

Query parameters

identifiersstring[] required

The reference(s) to resolve: a URL, an issue key such as PA-1787, or a bare external system ID. Repeat the parameter to batch: ?identifiers=PA-1787&identifiers=PA-1788. Maximum 10.

connectorNamestring

Optional hint that prioritises resolution order, e.g. JIRA, CONFLUENCE, DRIVE, SLACK (the ConnectorNameEnum values). Any other non-empty string is accepted too and simply matches no connector, so it changes nothing. It cannot widen the search beyond the connectors the caller can already access. Useful on a retry when a lookup came back empty. An empty or blank value is refused with 400 (the value is trimmed before it is checked).

Response

Successful operation. Identifiers that resolved to nothing the caller can access are echoed in not_found_identifiers rather than producing an error status.

ambiguousboolean required

True when one identifier resolved to more than one accessible record. Present the choice rather than taking the first, or retry with connectorName.

not_found_identifiersstring[] required

Identifiers that resolved to nothing the caller can access.

searched_connectorsobject

Per-identifier list of the connector types that were searched, so a miss can be retried against a different connectorName. Keys are the identifiers exactly as supplied.

textstring required

Flat-text rendering of the matches — each match's metadata block followed by a Next: line naming a follow-up call — and a line per miss naming the connectors that were searched. Capped at 25,000 bytes.

Changes

  • dbb5e203b445Revision changes
    • breaking

      removed the enum value ATTACHMENTS from the query request parameter connectorName

    • breaking

      removed the enum value AZURE BLOB from the query request parameter connectorName

    • breaking

      removed the enum value AZURE FILES from the query request parameter connectorName

    • breaking

      removed the enum value BOOKSTACK from the query request parameter connectorName

    • breaking

      removed the enum value BOX from the query request parameter connectorName

    • breaking

      removed the enum value CALENDAR from the query request parameter connectorName

    • breaking

      removed the enum value CODING_SANDBOX from the query request parameter connectorName

    • breaking

      removed the enum value CONFLUENCE from the query request parameter connectorName

    • breaking

      removed the enum value CONFLUENCE DATA CENTER from the query request parameter connectorName

    • breaking

      removed the enum value CONFLUENCE DATA CENTER PERSONAL from the query request parameter connectorName

    • breaking

      removed the enum value DATABASE_SANDBOX from the query request parameter connectorName

    • breaking

      removed the enum value DRIVE from the query request parameter connectorName

    • breaking

      removed the enum value DRIVE WORKSPACE from the query request parameter connectorName

    • breaking

      removed the enum value DROPBOX from the query request parameter connectorName

    • breaking

      removed the enum value DROPBOX PERSONAL from the query request parameter connectorName

    • breaking

      removed the enum value DRUPAL WIKI from the query request parameter connectorName

    • breaking

      removed the enum value GCS from the query request parameter connectorName

    • breaking

      removed the enum value GITHUB from the query request parameter connectorName

    • breaking

      removed the enum value GITHUB TEAMS from the query request parameter connectorName

    • breaking

      removed the enum value GITLAB from the query request parameter connectorName

    • breaking

      removed the enum value GITLAB PERSONAL from the query request parameter connectorName

    • breaking

      removed the enum value GMAIL from the query request parameter connectorName

    • breaking

      removed the enum value GMAIL WORKSPACE from the query request parameter connectorName

    • breaking

      removed the enum value IMAGE_GENERATION from the query request parameter connectorName

    • breaking

      removed the enum value JIRA from the query request parameter connectorName

    • breaking

      removed the enum value JIRA DATA CENTER from the query request parameter connectorName

    • breaking

      removed the enum value JIRA DATA CENTER PERSONAL from the query request parameter connectorName

    • breaking

      removed the enum value JIRA PERSONAL from the query request parameter connectorName

    • breaking

      removed the enum value KB from the query request parameter connectorName

    • breaking

      removed the enum value LINEAR from the query request parameter connectorName

    • breaking

      removed the enum value LOCAL_FS from the query request parameter connectorName

    • breaking

      removed the enum value MARIADB from the query request parameter connectorName

    • breaking

      removed the enum value MICROSOFT TEAMS from the query request parameter connectorName

    • breaking

      removed the enum value MINIO from the query request parameter connectorName

    • breaking

      removed the enum value NEXTCLOUD from the query request parameter connectorName

    • breaking

      removed the enum value NOTION from the query request parameter connectorName

    • breaking

      removed the enum value NOTION PERSONAL from the query request parameter connectorName

    • breaking

      removed the enum value ONEDRIVE from the query request parameter connectorName

    • breaking

      removed the enum value OUTLOOK from the query request parameter connectorName

    • breaking

      removed the enum value OUTLOOK CALENDAR from the query request parameter connectorName

    • breaking

      removed the enum value OUTLOOK PERSONAL from the query request parameter connectorName

    • breaking

      removed the enum value POSTGRESQL from the query request parameter connectorName

    • breaking

      removed the enum value RSS from the query request parameter connectorName

    • breaking

      removed the enum value S3 from the query request parameter connectorName

    • breaking

      removed the enum value SALESFORCE from the query request parameter connectorName

    • breaking

      removed the enum value SERVICENOW from the query request parameter connectorName

    • breaking

      removed the enum value SHAREPOINT ONLINE from the query request parameter connectorName

    • breaking

      removed the enum value SLACK from the query request parameter connectorName

    • breaking

      removed the enum value SLACK WORKSPACE from the query request parameter connectorName

    • breaking

      removed the enum value SNOWFLAKE from the query request parameter connectorName

    • breaking

      removed the enum value UNKNOWN from the query request parameter connectorName

    • breaking

      removed the enum value WEB from the query request parameter connectorName

    • breaking

      removed the enum value ZAMMAD from the query request parameter connectorName

    • breaking

      removed the enum value ZENDESK from the query request parameter connectorName

    • breaking

      removed the enum value ZOOM from the query request parameter connectorName

    • breaking

      for the query request parameter connectorName, the minLength was increased from 0 to 1

    • breaking

      added the pattern \S to the query request parameter connectorName

    • info

      the security scope kb:read was added to the endpoint's security scheme oauth2

    • info

      the security scope connector:read was removed from the endpoint's security scheme oauth2

  • a90ab79f26a1Revision changes
    • info

      added the new enum value ZENDESK to the query request parameter connectorName