---
title: "Resolve a URL, issue key or external ID to a Record ID"
method: GET
path: "/connectors/record/lookup"
tags: ["Connector"]
---

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

`GET /connectors/record/lookup`

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.

## Query parameters

- `identifiers` string[], required
- `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.

## Response `200`

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

- LookupRecordResponseSchema — Response returned by GET /connectors/record/lookup. Field names are snake_case, matching the knowledge graph's internal view models. A miss is a 200 with an empty `matches` and the input echoed in `not_found_identifiers` — see the endpoint description.
  - `matches` KnowledgeGraphLookupMatchSchema[], required
    - `id` string, required — The Record ID. Pass it to GET /connectors/record/{recordId}/content to read the record, or as `nodeId` to GET /connectors/navigate to list what is under it.
    - `name` string, required
    - `record_type` string, nullable, required
    - `connector_name` string, nullable, required
    - `web_url` string, nullable, required
    - `indexing_status` string, nullable, required
    - `identifier_used` string, required — Which of the supplied identifiers produced this match.
    - `external_id` string, nullable — e.g. `PA-1787`, a Confluence page id, a Drive file id.
    - `context_block` string, nullable — Type-specific metadata for the record — for a ticket, status, assignee, priority and dates.
  - `ambiguous` boolean, 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_identifiers` string[], required — Identifiers that resolved to nothing the caller can access.
  - `searched_connectors` object — 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.
  - `text` string, 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.

## Other responses

- `400` — No non-blank identifier was supplied, or more than 10 were.
- `401` — Missing, invalid, expired, or revoked authentication
- `403` — OAuth token is missing both the `kb:read` and `connector:read` scopes.
- `404` — The authenticated user could not be resolved
- `500` — Internal server error while resolving identifiers
- `503` — Connector service unavailable or connection refused

---

[API](https://skmtc.net/pipeshub-ai/apis/pipeshub-api.md) · [All operations](https://skmtc.net/pipeshub-ai/apis/pipeshub-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pipeshub-ai/pipeshub-api/revisions/64bfe76b130e/schema)