---
title: "Resolve Play Identity"
method: GET
path: "/api/plays/resolve"
tags: ["plays"]
---

# Resolve Play Identity

`GET /api/plays/resolve`

## Request

- Base URL: `https://platform.verbiflow.com/api/bridge`
- URL: `https://platform.verbiflow.com/api/bridge/api/plays/resolve`
- Auth: one of:
  - HTTP bearer and API key in header `x-flage-org-id`
  - HTTP bearer and API key in header `x-flage-org-slug`

Resolve authority only from canonical ids or exact persisted identities.

## Query parameters

- `query` string, required
- `include_hidden` boolean

## Response `200`

Successful Response

- union
  - PlayIdentityResolvedResponse: One authoritative exact workspace-scoped Play identity.
    - `play` PlayIdentityCandidate, required: One canonical Play plus the stored identity evidence that found it.
      - `code_revision_id` string, nullable: Current immutable code revision id when one is published.
      - `kind` 'workflow_play' | 'uploaded_play', required: Canonical stored Play kind.
      - `local_root_label` string, nullable: Current portable authoring-root label for a Workflow Play.
      - `match` PlayIdentityMatch, required: Why one workspace-scoped Play identity matched the caller's query.
        - `current` boolean, required: Whether this identity is current. Declared aliases remain searchable after removal as historical evidence, so callers must not infer this from provenance.
        - `exact` boolean, required: Whether this match is authoritative exact identity rather than fuzzy recall.
        - `matched_on` 'canonical_id' | 'current_title' | 'historical_title' | 'current_workflow_slug' | 'historical_workflow_slug' | 'current_workflow_name' | 'historical_workflow_name' | 'current_local_root_label' | 'historical_local_root_label' | 'declared_alias' | 'uploaded_play_title', required: Exact identity field or persisted alias class that matched.
        - `matched_value` string, required: Stored identity value that matched the query.
        - `provenance` 'canonical' | 'current' | 'historical' | 'declared', required: Authority provenance of the stored identity value.
        - `score` number, required: Similarity score; exact identities always use 1.0.
        - `source_code_revision_id` string, nullable: Revision where this identity was last current or declared, when known.
      - `play_id` string, required: Canonical workspace-scoped Play id.
      - `title` string, required: Current human-facing Play title.
      - `workflow_name` string, nullable: Current declared workflow name for a Workflow Play.
      - `workflow_slug` string, nullable: Current stable workflow slug for a Workflow Play.
    - `status` 'resolved', required: Authoritative exact-resolution state.
  - PlayIdentityCandidatesResponse: Non-authoritative candidates that require an explicit caller selection.
    - `candidates` PlayIdentityCandidate[], required: Bounded candidates with exact match provenance or fuzzy recall evidence.
      - `code_revision_id` string, nullable: Current immutable code revision id when one is published.
      - `kind` 'workflow_play' | 'uploaded_play', required: Canonical stored Play kind.
      - `local_root_label` string, nullable: Current portable authoring-root label for a Workflow Play.
      - `match` PlayIdentityMatch, required: Why one workspace-scoped Play identity matched the caller's query.
        - `current` boolean, required: Whether this identity is current. Declared aliases remain searchable after removal as historical evidence, so callers must not infer this from provenance.
        - `exact` boolean, required: Whether this match is authoritative exact identity rather than fuzzy recall.
        - `matched_on` 'canonical_id' | 'current_title' | 'historical_title' | 'current_workflow_slug' | 'historical_workflow_slug' | 'current_workflow_name' | 'historical_workflow_name' | 'current_local_root_label' | 'historical_local_root_label' | 'declared_alias' | 'uploaded_play_title', required: Exact identity field or persisted alias class that matched.
        - `matched_value` string, required: Stored identity value that matched the query.
        - `provenance` 'canonical' | 'current' | 'historical' | 'declared', required: Authority provenance of the stored identity value.
        - `score` number, required: Similarity score; exact identities always use 1.0.
        - `source_code_revision_id` string, nullable: Revision where this identity was last current or declared, when known.
      - `play_id` string, required: Canonical workspace-scoped Play id.
      - `title` string, required: Current human-facing Play title.
      - `workflow_name` string, nullable: Current declared workflow name for a Workflow Play.
      - `workflow_slug` string, nullable: Current stable workflow slug for a Workflow Play.
    - `reason` 'ambiguous_exact_match' | 'fuzzy_candidates', required: Why the server refused to choose one canonical Play.
    - `status` 'candidates', required: Non-authoritative candidate state.
  - PlayIdentityNotFoundResponse: No exact identity or bounded fuzzy candidate exists in this workspace.
    - `candidates` PlayIdentityCandidate[]: Always empty when no identity or candidate exists.
      - `code_revision_id` string, nullable: Current immutable code revision id when one is published.
      - `kind` 'workflow_play' | 'uploaded_play', required: Canonical stored Play kind.
      - `local_root_label` string, nullable: Current portable authoring-root label for a Workflow Play.
      - `match` PlayIdentityMatch, required: Why one workspace-scoped Play identity matched the caller's query.
        - `current` boolean, required: Whether this identity is current. Declared aliases remain searchable after removal as historical evidence, so callers must not infer this from provenance.
        - `exact` boolean, required: Whether this match is authoritative exact identity rather than fuzzy recall.
        - `matched_on` 'canonical_id' | 'current_title' | 'historical_title' | 'current_workflow_slug' | 'historical_workflow_slug' | 'current_workflow_name' | 'historical_workflow_name' | 'current_local_root_label' | 'historical_local_root_label' | 'declared_alias' | 'uploaded_play_title', required: Exact identity field or persisted alias class that matched.
        - `matched_value` string, required: Stored identity value that matched the query.
        - `provenance` 'canonical' | 'current' | 'historical' | 'declared', required: Authority provenance of the stored identity value.
        - `score` number, required: Similarity score; exact identities always use 1.0.
        - `source_code_revision_id` string, nullable: Revision where this identity was last current or declared, when known.
      - `play_id` string, required: Canonical workspace-scoped Play id.
      - `title` string, required: Current human-facing Play title.
      - `workflow_name` string, nullable: Current declared workflow name for a Workflow Play.
      - `workflow_slug` string, nullable: Current stable workflow slug for a Workflow Play.
    - `status` 'not_found', required: No workspace-scoped identity found state.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract.md) - [All operations](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract/llms.txt) - [OpenAPI document](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract/revisions/c80e903ef8f3?raw)