grovs API

openapi: 3.1.0
info:
  title: grovs API
  version: '2026-11-10'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-10: 18 operation(s) read from 5 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; grovs has published no machine-readable contract that the pipeline
    could find. Engine: local.'
  x-evidence-tiers:
    code-example: 6
    documentation: 12
    pages-with-code: 5
    pages-read: 5
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-10'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://docs.grovs.io/docs/api-reference
  - https://docs.grovs.io/docs/api-reference.md
  - https://docs.grovs.io/docs/api-reference/links
  - https://docs.grovs.io/docs/api-reference/links.md
  - https://docs.grovs.io/docs/api-reference/segments
paths:
  /:
    get:
      operationId: get
      tags:
      - Api
      summary: GET /
      x-source: https://docs.grovs.io/docs/api-reference/segments
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl JavaScript Python Go Rust Ruby Create, count and archive segments from your server, and upload the identifier lists they
          match. Segments A segment is a saved set of conditions, such as "iOS users who bought pro_yearly in the last 90 days". Use it as the
          audience of a server push , an in-app message or a journey. The concepts are in the Segments guide . These endpoints live on the SDK
          host: ht'
    post:
      operationId: post
      tags:
      - Api
      summary: POST /
      x-source: https://docs.grovs.io/docs/api-reference/links
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl JavaScript Python Go Rust Ruby Create links from your server and read their details and lifetime metrics. Links Create
          links from your server. Read their details and lifetime metrics. These endpoints live on the SDK host: https://sdk.sqd.link on grovs
          Cloud, https://sdk.<SERVER_HOST> when you self-host. Send your project key in the PROJECT-KEY header. Send production or test in the
          ENVIRONMEN'
  /api/v1/sdk/generate_link:
    post:
      operationId: post_api_v1_sdk_generate_link
      tags:
      - Api
      summary: POST /api/v1/sdk/generate_link
      x-source: https://docs.grovs.io/docs/api-reference/links.md
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1SdkGenerateLinkRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1SdkGenerateLinkResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST \"https://sdk.sqd.link/api/v1/sdk/generate_link\"  -H \"PROJECT-KEY: $GROVS_PROJECT_KEY\"  -H \"ENVIRONMENT: production\"\
          \  -H \"Content-Type: application/json\"  -d '{\n  \"title\": \"Book a check-up\",\n  \"subtitle\": \"Same-week appointments at Medly\
          \ clinics\",\n  \"data\": \"{\\\"screen\\\":\\\"booking\\\",\\\"clinic_id\\\":\\\"42\\\"}\",\n  \"tags\": \"[\\\"clinics\\\",\\\"autumn\\\
          \"]\",\n  \"ios_custom_redirect\": {\n    \"url\": \"http"
  /api/v1/sdk/metrics_for_project:
    get:
      operationId: get_api_v1_sdk_metrics_for_project
      tags:
      - Api
      summary: GET /api/v1/sdk/metrics_for_project
      x-source: https://docs.grovs.io/docs/api-reference
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1SdkMetricsForProjectResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl JavaScript Python Go Rust Ruby The grovs REST API: base URLs, request format, IDs and the resources you can call from your
          server. Introduction Use the grovs REST API from your servers and scripts. Create links and read their metrics, manage segments and
          in-app messages, send transactional pushes, and pull your event data and audit log. Every request and response body is JSON. Send Content-Ty'
  /api/v1/sdk/server/segments:
    get:
      operationId: get_api_v1_sdk_server_segments
      tags:
      - Api
      summary: List segments
      description: Returns up to 200 segments of the environment, most recently updated first.
      x-source: https://docs.grovs.io/docs/api-reference/segments
      parameters:
      - name: archived
        in: query
        required: false
        schema:
          type: boolean
        description: true lists archived segments instead of active ones.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1SdkServerSegmentsResponse'
      x-evidence:
        kind: documentation
  /api/v1/sdk/server/segments/{segmentId}:
    get:
      operationId: get_api_v1_sdk_server_segments_segmentId
      tags:
      - Api
      summary: Retrieve a segment
      description: Returns one segment, archived or not.
      x-source: https://docs.grovs.io/docs/api-reference/segments
      parameters:
      - name: segmentId
        in: path
        required: true
        schema:
          type: string
      - name: PROJECT-KEY
        in: header
        required: true
        schema:
          type: string
        description: Your project key.
      - name: ENVIRONMENT
        in: header
        required: true
        schema:
          type: string
        description: production or test.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1SdkServerSegmentsSegmentidResponse'
      x-evidence:
        kind: documentation
  /sdk/generate_link:
    post:
      operationId: post_sdk_generate_link
      tags:
      - Sdk
      summary: Generate a link
      x-source: https://docs.grovs.io/docs/api-reference/links
      parameters:
      - name: PROJECT-KEY
        in: header
        required: true
        schema:
          type: string
        description: Your project key. Find it in Developers › API Key in the dashboard.
      - name: ENVIRONMENT
        in: header
        required: true
        schema:
          type: string
        description: production or test. Any other value returns 400.
      - name: Content-Type
        in: header
        required: true
        schema:
          type: string
        description: application/json
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostSdkGenerateLinkRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostSdkGenerateLinkResponse'
      x-evidence:
        kind: documentation
  /sdk/link/{linkPath}:
    get:
      operationId: get_sdk_link_linkPath
      tags:
      - Sdk
      summary: Get link details
      x-source: https://docs.grovs.io/docs/api-reference/links
      parameters:
      - name: linkPath
        in: path
        required: true
        schema:
          type: string
      - name: PROJECT-KEY
        in: header
        required: true
        schema:
          type: string
        description: Your project key.
      - name: ENVIRONMENT
        in: header
        required: true
        schema:
          type: string
        description: production or test.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSdkLinkLinkpathResponse'
      x-evidence:
        kind: documentation
  /sdk/metrics_for_link/{linkPath}:
    get:
      operationId: get_sdk_metrics_for_link_linkPath
      tags:
      - Sdk
      summary: Get link metrics
      x-source: https://docs.grovs.io/docs/api-reference/links
      parameters:
      - name: linkPath
        in: path
        required: true
        schema:
          type: string
      - name: PROJECT-KEY
        in: header
        required: true
        schema:
          type: string
        description: Your project key.
      - name: ENVIRONMENT
        in: header
        required: true
        schema:
          type: string
        description: production or test.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSdkMetricsForLinkLinkpathResponse'
      x-evidence:
        kind: documentation
  /sdk/metrics_for_project:
    get:
      operationId: get_sdk_metrics_for_project
      tags:
      - Sdk
      summary: Get project metrics
      x-source: https://docs.grovs.io/docs/api-reference/links
      parameters:
      - name: PROJECT-KEY
        in: header
        required: true
        schema:
          type: string
        description: Your project key.
      - name: ENVIRONMENT
        in: header
        required: true
        schema:
          type: string
        description: production or test.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSdkMetricsForProjectResponse'
      x-evidence:
        kind: documentation
  /sdk/server/segments:
    get:
      operationId: get_sdk_server_segments
      tags:
      - Sdk
      summary: List segments
      description: Returns up to 200 segments of the environment, most recently updated first.
      x-source: https://docs.grovs.io/docs/api-reference/segments
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSdkServerSegmentsResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_sdk_server_segments
      tags:
      - Sdk
      summary: Create a segment
      description: Saves a segment. The definition is validated and stored in canonical form.
      x-source: https://docs.grovs.io/docs/api-reference/segments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostSdkServerSegmentsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostSdkServerSegmentsResponse'
      x-evidence:
        kind: documentation
  /sdk/server/segments/{segmentId}:
    delete:
      operationId: delete_sdk_server_segments_segmentId
      tags:
      - Sdk
      summary: Archive a segment
      description: Archives the segment. It is not deleted.
      x-source: https://docs.grovs.io/docs/api-reference/segments
      parameters:
      - name: segmentId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteSdkServerSegmentsSegmentidResponse'
      x-evidence:
        kind: documentation
    get:
      operationId: get_sdk_server_segments_segmentId
      tags:
      - Sdk
      summary: Retrieve a segment
      description: Returns one segment, archived or not.
      x-source: https://docs.grovs.io/docs/api-reference/segments
      parameters:
      - name: segmentId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSdkServerSegmentsSegmentidResponse'
      x-evidence:
        kind: documentation
    patch:
      operationId: patch_sdk_server_segments_segmentId
      tags:
      - Sdk
      summary: Update a segment
      description: Changes only the fields you send.
      x-source: https://docs.grovs.io/docs/api-reference/segments
      parameters:
      - name: segmentId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchSdkServerSegmentsSegmentidRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchSdkServerSegmentsSegmentidResponse'
      x-evidence:
        kind: documentation
  /sdk/server/segments/{segmentId}/count:
    post:
      operationId: post_sdk_server_segments_segmentId_count
      tags:
      - Sdk
      summary: Count a segment
      description: Returns the exact number of people and devices in a saved segment.
      x-source: https://docs.grovs.io/docs/api-reference/segments
      parameters:
      - name: segmentId
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostSdkServerSegmentsSegmentidCountResponse'
      x-evidence:
        kind: documentation
  /sdk/server/segments/{segmentId}/identifier_list:
    post:
      operationId: post_sdk_server_segments_segmentId_identifier_list
      tags:
      - Sdk
      summary: Replace the identifier list
      description: Stores a list of your user IDs on the segment, replacing any earlier list.
      x-source: https://docs.grovs.io/docs/api-reference/segments
      parameters:
      - name: segmentId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostSdkServerSegmentsSegmentidIdentifierListRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostSdkServerSegmentsSegmentidIdentifierListResponse'
      x-evidence:
        kind: documentation
  /sdk/server/segments/estimate:
    post:
      operationId: post_sdk_server_segments_estimate
      tags:
      - Sdk
      summary: Estimate a segment
      description: Counts the people and devices a definition matches without saving it.
      x-source: https://docs.grovs.io/docs/api-reference/segments
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostSdkServerSegmentsEstimateRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostSdkServerSegmentsEstimateResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    PostRequest:
      type: object
      properties:
        title:
          type: string
        subtitle:
          type: string
        data:
          type: string
        tags:
          type: string
        ios_custom_redirect:
          type: object
          properties:
            url:
              type: string
            open_app_if_installed:
              type: boolean
        android_custom_redirect:
          type: object
          properties:
            url:
              type: string
            open_app_if_installed:
              type: boolean
        desktop_custom_redirect:
          type: object
          properties:
            url:
              type: string
        show_preview_ios:
          type: boolean
        show_preview_android:
          type: boolean
        tracking_campaign:
          type: string
        tracking_source:
          type: string
        tracking_medium:
          type: string
    PostApiV1SdkGenerateLinkRequest:
      type: object
      properties:
        title:
          type: string
        subtitle:
          type: string
        data:
          type: string
        tags:
          type: string
        ios_custom_redirect:
          type: object
          properties:
            url:
              type: string
            open_app_if_installed:
              type: boolean
        android_custom_redirect:
          type: object
          properties:
            url:
              type: string
            open_app_if_installed:
              type: boolean
        desktop_custom_redirect:
          type: object
          properties:
            url:
              type: string
        show_preview_ios:
          type: boolean
        show_preview_android:
          type: boolean
        tracking_campaign:
          type: string
        tracking_source:
          type: string
        tracking_medium:
          type: string
    PostApiV1SdkGenerateLinkResponse:
      type: object
      properties:
        link:
          type: string
    GetApiV1SdkMetricsForProjectResponse:
      type: object
      properties:
        error:
          type: string
    GetApiV1SdkServerSegmentsResponse:
      type: object
      properties:
        segments:
          type: array
          description: list of segment objects
        truncated:
          type: boolean
          description: true when there are more than 200
    GetApiV1SdkServerSegmentsSegmentidResponse:
      type: object
      properties:
        segment:
          type: object
          description: A segment object.
    PostSdkGenerateLinkRequest:
      type: object
      properties:
        title:
          type: string
          description: Title shown in the link preview.
        subtitle:
          type: string
          description: Subtitle shown in the link preview.
        data:
          type: string
          description: Stringified JSON object delivered to your app by the SDK when the link opens it.
        tags:
          type: string
          description: Stringified JSON array of tags.
        ios_custom_redirect:
          type: object
          description: iOS redirect with url and open_app_if_installed.
        android_custom_redirect:
          type: object
          description: Android redirect with url and open_app_if_installed.
        desktop_custom_redirect:
          type: object
          description: Desktop browser fallback with url.
        show_preview_ios:
          type: boolean
          description: Show the preview page on iOS.
        show_preview_android:
          type: boolean
          description: Show the preview page on Android.
        show_preview:
          type: boolean
          description: Shorthand for both platforms.
        copy_to_clipboard_ios:
          type: boolean
          description: Copy the link to the clipboard from the iOS preview page.
        copy_to_clipboard_android:
          type: boolean
          description: Copy the link to the clipboard from the Android preview page.
        tracking_campaign:
          type: string
          description: Campaign name.
        tracking_source:
          type: string
          description: Traffic source.
        tracking_medium:
          type: string
          description: Medium.
    PostSdkGenerateLinkResponse:
      type: object
      properties:
        link:
          type: string
          description: The new link's URL, ready to share.
    GetSdkLinkLinkpathResponse:
      type: object
      properties:
        link.id:
          type: integer
          description: Numeric link ID.
        link.name:
          type: string
          description: Name set in the dashboard.
        link.path:
          type: string
          description: Path of the link URL.
        link.access_path:
          type: string
          description: Full link URL.
        link.title:
          type: string
          description: Preview title.
        link.subtitle:
          type: string
          description: Preview subtitle.
        link.image:
          type: string
          description: Preview image URL.
        link.data:
          type: object
          description: Custom data parsed into an object.
        link.tags:
          type: array
          description: Tags of the link.
        link.active:
          type: boolean
          description: Whether the link is active.
        link.sdk_generated:
          type: boolean
          description: True for links created through the API or an SDK.
        link.generated_from_platform:
          type: string
          description: Where the link was created.
        link.ads_platform:
          type: string
          description: Ads platform the link was made for.
        link.campaign_id:
          type: integer
          description: Dashboard campaign ID.
        link.visitor_id:
          type: integer
          description: App user who created the link.
        link.updated_at:
          type: string
          description: ISO 8601 time of the last change.
        link.show_preview_ios:
          type: boolean
          description: Whether the preview page shows on iOS.
        link.show_preview_android:
          type: boolean
          description: Whether the preview page shows on Android.
        link.copy_to_clipboard_ios:
          type: boolean
          description: Clipboard copy setting for iOS.
        link.copy_to_clipboard_android:
          type: boolean
          description: Clipboard copy setting for Android.
        link.ios_custom_redirect:
          type: object
          description: iOS redirect object.
        link.android_custom_redirect:
          type: object
          description: Android redirect object.
        link.desktop_custom_redirect:
          type: object
          description: Desktop redirect object.
        link.tracking_campaign:
          type: string
          description: Campaign name.
        link.tracking_source:
          type: string
          description: Traffic source.
        link.tracking_medium:
          type: string
          description: Medium.
    GetSdkMetricsForLinkLinkpathResponse:
      type: object
      properties:
        metrics.id:
          type: integer
          description: Numeric link ID.
        metrics.name:
          type: string
          description: Name set in the dashboard.
        metrics.path:
          type: string
          description: Path of the link URL.
        metrics.title:
          type: string
          description: Preview title.
        metrics.subtitle:
          type: string
          description: Preview subtitle.
        metrics.active:
          type: boolean
          description: Whether the link is active.
        metrics.sdk_generated:
          type: boolean
          description: True for SDK-generated links.
        metrics.data:
          type: object
          description: Custom data.
        metrics.tags:
          type: array
          description: Tags of the link.
        metrics.updated_at:
          type: string
          description: ISO 8601 timestamp.
        metrics.show_preview_ios:
          type: boolean
          description: Preview on iOS.
        metrics.show_preview_android:
          type: boolean
          description: Preview on Android.
        metrics.copy_to_clipboard_ios:
          type: boolean
          description: Clipboard copy iOS.
        metrics.copy_to_clipboard_android:
          type: boolean
          description: Clipboard copy Android.
        metrics.ads_platform:
          type: string
          description: Ads platform.
        metrics.generated_from_platform:
          type: string
          description: Origin platform.
        metrics.tracking_source:
          type: string
          description: Traffic source.
        metrics.tracking_medium:
          type: string
          description: Medium.
        metrics.tracking_campaign:
          type: string
          description: Campaign name.
        metrics.visitor_id:
          type: integer
          description: Visitor ID.
        metrics.campaign_id:
          type: integer
          description: Campaign ID.
        metrics.total_views:
          type: integer
          description: Times the link was opened in a browser.
        metrics.total_opens:
          type: integer
          description: Times the link opened the app.
        metrics.total_installs:
          type: integer
          description: Installs attributed to the link.
        metrics.total_reinstalls:
          type: integer
          description: Reinstalls attributed to the link.
        metrics.total_time_spent:
          type: integer
          description: Total time in the app (seconds).
        metrics.total_reactivations:
          type: integer
          description: Users returning after 7+ days.
        metrics.total_app_opens:
          type: integer
          description: App opens by attributed users.
        metrics.total_user_referred:
          type: integer
          description: Installs referred by the link's creator.
        metrics.total_revenue:
          type: integer
          description: Revenue in cents.
    GetSdkMetricsForProjectResponse:
      type: object
      properties:
        '[]':
          type: array
          description: Array of metric objects, each with the same fields as Get link metrics.
    GetSdkServerSegmentsResponse:
      type: object
      properties:
        segments:
          type: array
          description: list of segment objects
        truncated:
          type: boolean
          description: true when there are more than 200
    PostSdkServerSegmentsRequest:
      type: object
      properties:
        name:
          type: string
          description: Up to 255 characters.
        description:
          type: string
          description: Free text.
        definition:
          type: object
          description: A definition.
      required:
      - name
      - definition
    PostSdkServerSegmentsResponse:
      type: object
      properties:
        segment:
          type: object
          description: The created segment object.
    DeleteSdkServerSegmentsSegmentidResponse:
      type: object
      properties:
        message:
          type: string
          description: Segment archived
    GetSdkServerSegmentsSegmentidResponse:
      type: object
      properties:
        segment:
          type: object
          description: A segment object.
    PatchSdkServerSegmentsSegmentidRequest:
      type: object
      properties:
        name:
          type: string
          description: Up to 255 characters.
        description:
          type: string
          description: Free text.
        definition:
          type: object
          description: A full definition.
        archived:
          type: boolean
          description: false restores an archived segment.
    PatchSdkServerSegmentsSegmentidResponse:
      type: object
      properties:
        segment:
          type: object
          description: Updated segment object.
    PostSdkServerSegmentsSegmentidCountResponse:
      type: object
      properties:
        persons:
          type: integer
          description: Number of persons.
        devices:
          type: integer
          description: Number of devices.
        incomplete:
          type: boolean
          description: Whether count may be low.
        result_id:
          type: string
          description: ID of the computed result.
    PostSdkServerSegmentsSegmentidIdentifierListRequest:
      type: object
      properties:
        identifiers:
          type: array
          description: 1 to 200,000 strings of 1 to 256 bytes.
      required:
      - identifiers
    PostSdkServerSegmentsSegmentidIdentifierListResponse:
      type: object
      properties:
        segment:
          type: object
          description: Updated segment.
        count:
          type: integer
          description: Number of distinct identifiers stored.
    PostSdkServerSegmentsEstimateRequest:
      type: object
      properties:
        definition:
          type: object
          description: A definition.
        segment_id:
          type: string
          description: An active segment.
    PostSdkServerSegmentsEstimateResponse:
      type: object
      properties:
        persons:
          type: integer
          description: count of persons
        devices:
          type: integer
          description: count of devices
        approximate:
          type: boolean
          description: 'always false: counts are exact'
        incomplete:
          type: boolean
          description: true when a window reaches past data retention
  securitySchemes:
    Project_key:
      type: apiKey
      in: header
      name: PROJECT-KEY
      x-source: https://docs.grovs.io/docs/api-reference/authentication.md
    Scoped_key:
      type: http
      scheme: bearer
      x-source: https://docs.grovs.io/docs/api-reference/authentication.md
tags:
- name: Api
- name: Sdk
security:
- Project_key: []
- Scoped_key: []