Sign in
OpenAPI 3.0.0raw.githubusercontent.com2026-08-1291215647.5 KB

11f5086fcbb8

Connector

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

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.

get/connectors/record/lookup

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.

connectorName'DRIVE' | 'DRIVE WORKSPACE' | 'GMAIL' | 'GMAIL WORKSPACE' | 'CALENDAR' | 'ONEDRIVE' | 'SHAREPOINT ONLINE' | 'OUTLOOK' | 'OUTLOOK PERSONAL' | 'OUTLOOK CALENDAR' | 'MICROSOFT TEAMS' | 'NOTION' | 'SLACK' | 'SLACK WORKSPACE' | 'KB' | 'CONFLUENCE' | 'CONFLUENCE DATA CENTER' | 'CONFLUENCE DATA CENTER PERSONAL' | 'JIRA' | 'JIRA PERSONAL' | 'JIRA DATA CENTER' | 'JIRA DATA CENTER PERSONAL' | 'BOX' | 'NEXTCLOUD' | 'DROPBOX' | 'DROPBOX PERSONAL' | 'WEB' | 'BOOKSTACK' | 'GITHUB' | 'SERVICENOW' | 'SALESFORCE' | 'S3' | 'MINIO' | 'GCS' | 'AZURE BLOB' | 'AZURE FILES' | 'LINEAR' | 'ZAMMAD' | 'ZOOM' | 'GITLAB' | 'GITLAB PERSONAL' | 'SNOWFLAKE' | 'POSTGRESQL' | 'MARIADB' | 'UNKNOWN' | 'RSS' | 'LOCAL_FS' | 'CODING_SANDBOX' | 'DATABASE_SANDBOX' | 'IMAGE_GENERATION' | 'ATTACHMENTS'

Name of the source connector. Mirrors the values of the backend Connectors enum (backend/python/app/config/constants/arangodb.py); records store the enum value (e.g. Google Drive is DRIVE, SharePoint Online is SHAREPOINT ONLINE), not the enum member name.

Example:DRIVE

Optional hint that prioritises resolution order, e.g. JIRA, CONFLUENCE, DRIVE, SLACK. Allowed values are the ConnectorNameEnum values. It cannot widen the search beyond the connectors the caller can already access. Useful on a retry when a lookup came back empty.

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.