> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heralded.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Share Brand Snapshot

> Make a restricted Snapshot unlisted and return its URL. Public links
keep their URL; revoked links stay revoked. Members need the existing
Snapshot sharing permission; service tokens need managed:share.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/brands/{brand_id}/snapshots/{share_id}/share
openapi: 3.1.0
info:
  description: >-
    Access to one organization's brands, as the member who created the API key.
    A read-only key reads; a full-access key also starts, edits and runs that
    member's Snapshots on the organization's Snapshot credits. Each key may make
    120 requests a minute. Separate organization service tokens can start
    Snapshots and Full audits and read service audits. Every error is an RFC
    9457 problem (`application/problem+json`) whose `code` names it.
  summary: Read your brands' AI visibility and run Snapshots in Heralded.
  title: Heralded API
  version: '1'
servers:
  - url: https://api.heralded.ai
security: []
paths:
  /v1/brands/{brand_id}/snapshots/{share_id}/share:
    post:
      tags:
        - v1
      summary: Share Brand Snapshot
      description: |-
        Make a restricted Snapshot unlisted and return its URL. Public links
        keep their URL; revoked links stay revoked. Members need the existing
        Snapshot sharing permission; service tokens need managed:share.
      operationId: shareBrandSnapshot
      parameters:
        - description: The brand's UUID from listBrands.
          in: path
          name: brand_id
          required: true
          schema:
            description: The brand's UUID from listBrands.
            format: uuid
            title: Brand Id
            type: string
        - description: The report link id from getBrandSnapshots.
          in: path
          name: share_id
          required: true
          schema:
            description: The report link id from getBrandSnapshots.
            format: uuid
            title: Share Id
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1SnapshotShare'
          description: Successful Response
        '400':
          content:
            application/problem+json:
              example:
                code: invalid_cursor
                detail: The cursor is invalid or belongs to a different query.
                instance: example-request-id
                status: 400
                title: Bad Request
                type: https://docs.heralded.ai/errors-and-limits#invalid_cursor
              schema:
                $ref: '#/components/schemas/Problem'
          description: The cursor is invalid or belongs to a different query.
        '401':
          content:
            application/problem+json:
              example:
                code: invalid_token
                detail: >-
                  The Authorization header carries no API key Heralded knows: it
                  is missing, mistyped, revoked or expired.
                instance: example-request-id
                status: 401
                title: Unauthorized
                type: https://docs.heralded.ai/errors-and-limits#invalid_token
              schema:
                $ref: '#/components/schemas/Problem'
          description: No API key, or one that is unknown, revoked or expired.
          headers:
            WWW-Authenticate:
              schema:
                example: Bearer
                type: string
        '403':
          content:
            application/problem+json:
              example:
                code: insufficient_scope
                detail: >-
                  The credential does not have the scope this operation
                  requires.
                instance: example-request-id
                status: 403
                title: Forbidden
                type: https://docs.heralded.ai/errors-and-limits#insufficient_scope
              schema:
                $ref: '#/components/schemas/Problem'
          description: The service token lacks the required scope.
          headers:
            WWW-Authenticate:
              schema:
                type: string
        '404':
          content:
            application/problem+json:
              example:
                code: not_found
                detail: Nothing here that this API key can read.
                instance: example-request-id
                status: 404
                title: Not Found
                type: https://docs.heralded.ai/errors-and-limits#not_found
              schema:
                $ref: '#/components/schemas/Problem'
          description: No such brand or answer, or the key's owner cannot read it.
        '409':
          content:
            application/problem+json:
              example:
                code: snapshot_revoked
                detail: Conflict
                instance: example-request-id
                status: 409
                title: Conflict
                type: https://docs.heralded.ai/errors-and-limits#snapshot_revoked
              schema:
                $ref: '#/components/schemas/Problem'
          description: The Snapshot's link is revoked.
        '422':
          content:
            application/problem+json:
              example:
                code: invalid_request
                detail: The request's parameters are invalid; `errors` names each one.
                errors:
                  - loc:
                      - query
                      - limit
                    msg: Input should be less than or equal to 100
                    type: less_than_equal
                instance: example-request-id
                status: 422
                title: Unprocessable Content
                type: https://docs.heralded.ai/errors-and-limits#invalid_request
              schema:
                $ref: '#/components/schemas/ValidationProblem'
          description: A path or query parameter is invalid.
        '429':
          content:
            application/problem+json:
              example:
                code: rate_limited
                detail: >-
                  This caller is past its requests for the minute. Retry after
                  the seconds in Retry-After.
                instance: example-request-id
                rate_limit:
                  limit: 120
                  remaining: 0
                  reset: 60
                  window: 60
                status: 429
                title: Too Many Requests
                type: https://docs.heralded.ai/errors-and-limits#rate_limited
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
          description: The API key made more than 120 requests in the minute.
          headers:
            Retry-After:
              description: Seconds until the key may call again.
              schema:
                example: 60
                type: integer
      security:
        - serviceToken: []
        - apiKey: []
components:
  schemas:
    V1SnapshotShare:
      properties:
        share_url:
          description: The unlisted Snapshot URL, which opens signed out.
          title: Share Url
          type: string
      required:
        - share_url
      title: V1SnapshotShare
      type: object
    Problem:
      description: An RFC 9457 problem linking its code to human-readable documentation.
      properties:
        code:
          title: Code
          type: string
        detail:
          title: Detail
          type: string
        instance:
          default: ''
          title: Instance
          type: string
        status:
          title: Status
          type: integer
        title:
          title: Title
          type: string
        type:
          title: Type
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
        - instance
      title: Problem
      type: object
    ValidationProblem:
      properties:
        code:
          title: Code
          type: string
        detail:
          title: Detail
          type: string
        errors:
          items:
            $ref: '#/components/schemas/ValidationIssue'
          title: Errors
          type: array
        instance:
          default: ''
          title: Instance
          type: string
        status:
          title: Status
          type: integer
        title:
          title: Title
          type: string
        type:
          title: Type
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
        - instance
        - errors
      title: ValidationProblem
      type: object
    RateLimitProblem:
      properties:
        code:
          title: Code
          type: string
        detail:
          title: Detail
          type: string
        instance:
          default: ''
          title: Instance
          type: string
        rate_limit:
          $ref: '#/components/schemas/RateLimitValues'
        status:
          title: Status
          type: integer
        title:
          title: Title
          type: string
        type:
          title: Type
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
        - instance
        - rate_limit
      title: RateLimitProblem
      type: object
    ValidationIssue:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Loc
          type: array
        msg:
          title: Msg
          type: string
        type:
          title: Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationIssue
      type: object
    RateLimitValues:
      properties:
        limit:
          title: Limit
          type: integer
        remaining:
          title: Remaining
          type: integer
        reset:
          title: Reset
          type: integer
        window:
          title: Window
          type: integer
      required:
        - limit
        - window
        - remaining
        - reset
      title: RateLimitValues
      type: object
  securitySchemes:
    serviceToken:
      description: >-
        An organisation service token, sent as Authorization: Bearer
        hrld_svc_... Scopes: scans:start starts service scans; scans:read reads
        them; managed:read reads brands, profile, overview, scores, competitors,
        actions and Snapshots in actively managed organisations; managed:share
        makes their restricted Snapshots unlisted.
      scheme: bearer
      type: http
    apiKey:
      description: 'An API key, sent as `Authorization: Bearer hrld_...`.'
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.