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

# Start or retry cell segmentation

> Start or retry idempotent, credit-free segmentation for an owned ready sample.

Active/completed work is reused. Failed work can be retried after the cooldown. Public, archived, cross-organization, and non-ready samples cannot be mutated.


## OpenAPI

````yaml POST /samples/{id}/segmentation
openapi: 3.1.0
info:
  title: Strand AI Platform API
  version: v1
  description: >-
    REST surface for uploading WSIs, submitting Lattice inference jobs, and
    streaming results. All endpoints require an API key or Strand AI OAuth
    access token in the `Authorization: Bearer` header.
servers:
  - url: https://app.strandai.com/api/v1
    description: Production
security:
  - ApiKey: []
  - OAuth2: []
paths:
  /samples/{id}/segmentation:
    post:
      summary: Start or retry cell segmentation
      description: >-
        State-idempotent and credit-free. Reuses completed/active work, retries
        failed work after a 60-second cooldown, and rejects non-ready, archived,
        cross-org, and public samples.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Existing completed or active work
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentationState'
        '202':
          description: Start/retry queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentationState'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: OAuth token lacks a required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Owned sample not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Sample not ready or archived
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Retry cooldown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Segmentation is not configured in this environment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKey: []
        - OAuth2:
            - samples:read
            - samples:write
components:
  schemas:
    SegmentationState:
      type: object
      additionalProperties: false
      required:
        - status
        - retryable
        - creditCost
        - job
        - layer
      properties:
        status:
          type: string
          enum:
            - not_started
            - queued
            - running
            - postprocessing
            - completed
            - failed
            - cancelled
        retryable:
          type: boolean
        creditCost:
          type: integer
          enum:
            - 0
          description: Segmentation is credit-free.
        job:
          type: object
          nullable: true
          additionalProperties: true
        layer:
          type: object
          nullable: true
          additionalProperties: true
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
        message:
          type: string
        required:
          type: integer
          nullable: true
        retryAfterSeconds:
          type: integer
          nullable: true
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: sk-strand-XXXXXXXXXXXXXXXXXXXXXXXX
    OAuth2:
      type: oauth2
      description: >-
        Strand AI authorization-code flow with S256 PKCE, explicit organization
        consent, and RFC 8707 resource binding.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.strandai.com/oauth2/auth
          tokenUrl: https://auth.strandai.com/oauth2/token
          scopes:
            samples:read: Read slide metadata and estimates
            samples:write: Upload and change slides
            jobs:read: Read run status
            jobs:write: Start, export, or cancel runs
            results:read: Read and download results
            credits:spend: Reserve and spend organization credits

````