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

# List Locations

> List every location in your workspace.

List every location in the authenticated workspace. Each item is a non-secret
summary — including the lifecycle `status`, so you can spot locations that have
failed or need attention. The response is a **JSON array** (not an object), takes
no request body, and never returns raw secrets.

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.byteport.com/v1/locations \
    -H "Authorization: Bearer $BYTEPORT_API_KEY" \
    -H "User-Agent: my-app/1.0"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://api.byteport.com/v1/locations", {
    headers: {
      Authorization: `Bearer ${process.env.BYTEPORT_API_KEY}`,
      "User-Agent": "my-app/1.0",
    },
  });
  const locations = await res.json(); // an array
  ```

  ```python Python theme={null}
  import os, requests

  locations = requests.get(
      "https://api.byteport.com/v1/locations",
      headers={
          "Authorization": f"Bearer {os.environ['BYTEPORT_API_KEY']}",
          "User-Agent": "my-app/1.0",
      },
  ).json()  # a list
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  [
    {
      "id":         "3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83",
      "provider":   "s3",
      "label":      "prod-backups",
      "status":     "active",
      "created_at": "2026-05-14T17:02:11Z"
    },
    {
      "id":               "8c2e1f4a-9b3d-4e6f-a1c7-2d5b0e9f7a34",
      "provider":         "dropbox",
      "label":            "marketing-assets",
      "status":           "needs_attention",
      "validation_error": "refresh failed repeatedly",
      "created_at":       "2026-04-02T09:18:44Z"
    }
  ]
  ```
</ResponseExample>


## OpenAPI

````yaml GET /v1/locations
openapi: 3.1.0
info:
  title: Byteport API
  description: >-
    The Byteport API lets you move, share, and manage files across every storage
    location connected to your workspace through a single HTTP interface.
  version: 1.0.0
servers:
  - url: https://api.byteport.com
security:
  - bearerAuth: []
paths:
  /v1/locations:
    get:
      summary: List Locations
      description: >-
        List every location in the authenticated workspace. Each item is a
        non-secret summary including lifecycle `status`. The response is a JSON
        array, not an object, and takes no request body.
      responses:
        '200':
          description: The workspace's locations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LocationSummary'
        '401':
          $ref: '#/components/responses/Error'
components:
  schemas:
    LocationSummary:
      type: object
      description: >-
        The list projection of a location. Like `Location` but with lifecycle
        fields (`status`, `created_at`) instead of `metadata`, and never any
        secret material.
      properties:
        id:
          type: string
          description: Unique identifier for the location (a UUID).
          example: 3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83
        provider:
          type: string
          description: The storage backend this location authenticates against.
          example: s3
        label:
          type: string
          description: The human-readable name. Not unique across an account.
          example: prod-backups
        status:
          type: string
          description: >-
            Lifecycle state. `active` is healthy; `failed` is a provider's
            terminal rejection (e.g. an invalid grant); `needs_attention` is
            Byteport's back-off after repeated refresh failures, awaiting an
            operator.
          enum:
            - active
            - failed
            - needs_attention
          example: active
        validation_error:
          type: string
          description: Why the location was marked `failed`. Omitted for active locations.
          example: invalid_grant
        created_at:
          type: string
          format: date-time
          description: When the location was created (RFC 3339, UTC).
          example: '2026-05-14T17:02:11Z'
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: integer
        message:
          type: string
  responses:
    Error:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````