> ## 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.

# Refresh Location

> Queue a refresh of a location's secret.

Request a refresh of a location's secret. The call flags the location for
Byteport's background refresher and returns immediately with `202 Accepted` — the
refresh has been **queued, not completed**. Poll
[Get Location Status](/api-reference/locations/status) to observe the result.

Address the location by **`name`** or **`id`**; at least one is required. A
non-unique `name` returns `409` with the candidates — resend with the `id` of the
one you want.

This applies to providers whose secrets rotate (the OAuth providers — Dropbox,
Google Drive, OneDrive, Box). For static credentials it is effectively a no-op.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.byteport.com/v1/locations/refresh \
    -H "Authorization: Bearer $BYTEPORT_API_KEY" \
    -H "User-Agent: my-app/1.0" \
    -H "Content-Type: application/json" \
    -d '{ "name": "marketing-assets" }'
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://api.byteport.com/v1/locations/refresh", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BYTEPORT_API_KEY}`,
      "User-Agent": "my-app/1.0",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "marketing-assets" }), // or { id: "..." }
  });
  ```

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

  requests.post(
      "https://api.byteport.com/v1/locations/refresh",
      headers={
          "Authorization": f"Bearer {os.environ['BYTEPORT_API_KEY']}",
          "User-Agent": "my-app/1.0",
      },
      json={"name": "marketing-assets"},  # or {"id": "..."}
  )
  ```
</RequestExample>

<ResponseExample>
  ```text 202 Accepted theme={null}
  (empty body)
  ```

  ```json 404 Not Found theme={null}
  {
    "error": 404,
    "message": "no location named marketing-assets"
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /v1/locations/refresh
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/refresh:
    post:
      summary: Refresh Location
      description: >-
        Request a refresh of a location's secret, addressed by `name` or `id`.
        Returns `202` immediately — the refresh is queued for the background
        refresher, not completed. Poll Get Location Status to observe the
        result. Applies to providers whose secrets rotate (OAuth); a no-op for
        static credentials.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Address the location by `name` or `id`.
              properties:
                name:
                  type: string
                  description: >-
                    The location name (its `label`). Resolved to a single
                    location; if the name matches several, also send `id` to
                    pick one.
                  example: prod-backups
                id:
                  type: string
                  description: >-
                    The location's UUID. Addresses one location directly, or —
                    alongside `name` — selects which match of a non-unique name
                    to act on.
                  example: 3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83
      responses:
        '202':
          description: Refresh queued. The response body is empty.
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          description: The `name` matches more than one location; resend with an `id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationConflict'
components:
  responses:
    Error:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    LocationConflict:
      type: object
      description: >-
        Returned with `409` by a single-location endpoint when the `name` in the
        body matches more than one location. Re-issue the request with an `id`
        field set to one of the candidates.
      properties:
        error:
          type: string
          description: Human-readable explanation of the ambiguity.
          example: >-
            name is not unique; re-issue with an "id" field for one of the
            candidates
        name:
          type: string
          description: The ambiguous location name from the request body.
          example: prod-backups
        candidates:
          type: array
          description: >-
            Every location that carries this name. Choose one and resend with
            its `id`.
          items:
            $ref: '#/components/schemas/LocationRef'
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: integer
        message:
          type: string
    LocationRef:
      type: object
      description: >-
        A credential addressed by its label ("location name"). Because labels
        are not unique, a single name can resolve to several of these.
        `provider` and the timestamps let you tell same-named credentials apart
        and pick the `id` to act on.
      properties:
        id:
          type: string
          description: >-
            The credential's UUID. Pass it back as the `?id=` query parameter to
            disambiguate a non-unique name on the mutating Locations endpoints.
          example: 3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83
        provider:
          type: string
          description: The storage backend this credential authenticates against.
          example: s3
        created_at:
          type: string
          format: date-time
          description: When the credential was created (RFC 3339, UTC).
          example: '2026-05-14T17:02:11Z'
        updated_at:
          type: string
          format: date-time
          description: When the credential was last modified (RFC 3339, UTC).
          example: '2026-06-01T09:44:20Z'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````