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

# Rename or re-describe

> Title and description only. Sharing settings are deliberately not writable here. Renaming never changes the URL — it has already been sent to people.



## OpenAPI

````yaml /openapi.json patch /collections/{id}
openapi: 3.1.0
info:
  title: Yungle API
  version: 1.0.0
  description: >-
    Send transfers, build collections and sync contacts from your own systems.
    Every account can use it: transfers and contacts on the free plan,
    collections on a paid one.


    Lists that can grow without bound (transfers, collection files) take `limit`
    and `cursor` and return `nextCursor`; pass it back unchanged for the next
    page, and stop when it is null.


    Any POST accepts an `Idempotency-Key` header (1–255 printable characters; a
    UUID). A retry with the same key and body within 24 hours replays the
    original success with `Idempotent-Replayed: true` and creates nothing.


    File bytes never travel through this API: endpoints that accept files return
    a tus endpoint and a per-file upload token, and you stream to that. See
    https://docs.yungle.co/guides/upload-large-files.


    The vault and end-to-end encrypted transfers are not reachable here, and
    cannot be: their keys are derived in the client and never sent to us.


    **Errors** are JSON with a stable `error.code` (the `Error` schema);
    `error.docs` links to the explanation. See https://docs.yungle.co/errors.


    **Rate limits** are reported on every metered response in the IETF draft
    `RateLimit` and `RateLimit-Policy` headers, per key per minute and per
    workspace per day. A 429 carries `Retry-After` in seconds. See
    https://docs.yungle.co/limits.


    **Versioning.** The version is in the path. `/api/v1` changes additively
    only: new endpoints, optional fields and response fields may appear; nothing
    existing is removed, renamed or made required. A breaking change ships as
    `/api/v2`. An operation that is going away is marked `deprecated: true`
    here, answers with a `Deprecation` header (RFC 9745) and a `Sunset` header
    (RFC 8594) giving its last day, and is announced in the changelog at least
    six months before that day: https://docs.yungle.co/changelog. No v1
    operation is deprecated.
  contact:
    name: Yungle
    url: https://docs.yungle.co
  license:
    name: MIT
    identifier: MIT
  termsOfService: https://yungle.co/legal/terms
servers:
  - url: https://yungle.co/api/v1
security:
  - apiKey: []
tags:
  - name: Account
    description: Who the key is and what it may do.
  - name: Transfers
    description: One-off sends with an expiring link.
  - name: Collections
    description: Durable, folder-structured spaces clients are invited into.
  - name: Contacts
    description: The workspace address book.
  - name: Upload requests
    description: Public links that let other people send files into your collections.
  - name: Downloads
    description: >-
      Getting bytes out: signed, resumable URLs for your own transfers and
      collections, and for links shared with you.
  - name: Webhooks
    description: >-
      Events pushed to your URL, signed with `Yungle-Signature`, or kept for you
      to pull. See the Webhooks guide.
paths:
  /collections/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Collection id. Never a slug — see the Concepts page.
    patch:
      tags:
        - Collections
      summary: Rename or re-describe
      description: >-
        Title and description only. Sharing settings are deliberately not
        writable here. Renaming never changes the URL — it has already been sent
        to people.
      operationId: updateCollection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  minLength: 1
                  maxLength: 200
                description:
                  type: string
                  maxLength: 2000
              additionalProperties: false
              $schema: http://json-schema.org/draft-07/schema#
      responses:
        '200':
          description: The updated collection.
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection:
                    $ref: '#/components/schemas/Collection'
                required:
                  - collection
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  headers:
    RateLimit:
      description: >-
        What is left in each bucket this request was charged against, e.g.
        `"key";r=87;t=34, "workspace";r=19880;t=40211` (`r` remaining, `t`
        seconds until reset). draft-ietf-httpapi-ratelimit-headers.
      schema:
        type: string
    RateLimit-Policy:
      description: >-
        The buckets themselves, e.g. `"key";q=120;w=60,
        "workspace";q=20000;w=86400` (`q` quota, `w` window in seconds).
      schema:
        type: string
  schemas:
    Collection:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        slug:
          type: string
        description:
          type:
            - string
            - 'null'
        visibility:
          type: string
          description: >-
            Currently one of: `private`, `public`, `password`. Treat unknown
            values as unknown, not as an error.
        url:
          anyOf:
            - type: string
              format: uri
            - type: 'null'
          description: The secret link. Treat it like a password.
        customLink:
          type: boolean
          description: Whether the readable `<your-domain>/<slug>` address is on.
        sizeBytes:
          type: integer
          minimum: 0
        fileCount:
          type: integer
          minimum: 0
          description: Present on the single-collection read.
        coverFileId:
          type:
            - string
            - 'null'
        expiresAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          description: 'Null on a paid plan: nothing expires.'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - title
        - slug
        - description
        - visibility
        - url
        - customLink
        - sizeBytes
        - coverFileId
        - expiresAt
        - createdAt
        - updatedAt
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - unauthorized
                - insufficient_scope
                - upgrade_required
                - out_of_credit
                - not_found
                - invalid_request
                - folder_error
                - conflict
                - not_editable
                - quota_exceeded
                - transfer_too_large
                - rate_limited
                - email_budget_exhausted
                - password_required
                - wrong_password
                - guests_only
                - link_unavailable
                - e2ee_unsupported
                - internal_error
              description: >-
                Stable and machine-readable: branch on this. New codes may be
                added within an existing status.
            message:
              type: string
              description: For a human reading a log. May change; do not parse it.
            details:
              type: object
              additionalProperties: true
              description: >-
                Present only when there is something actionable, and shaped per
                code.
            docs:
              type: string
              format: uri
              description: The page that explains this code and what to do about it.
  responses:
    BadRequest:
      description: >-
        The request was malformed or failed validation. Codes:
        `invalid_request`, `folder_error`.
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: 'Missing or invalid credential. Codes: `unauthorized`.'
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description: >-
        Needs a paid plan, or prepaid credit for metered usage. Codes:
        `upgrade_required`, `out_of_credit`.
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >-
        The credential lacks a required scope, or a shared link refused access.
        Codes: `insufficient_scope`, `password_required`, `wrong_password`,
        `guests_only`.
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: 'No such resource in this workspace. Codes: `not_found`.'
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: >-
        Rate limit or email budget exhausted. Wait for `Retry-After`. Codes:
        `rate_limited`, `email_budget_exhausted`.
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: >-
        Our fault. `details.requestId` ties it to our logs. Codes:
        `internal_error`.
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        An API key from Settings → API keys, sent as `Authorization: Bearer
        yk_live_…`. Scopes: transfers:read, transfers:write, collections:read,
        collections:write, contacts:read, contacts:write, webhooks:read,
        webhooks:write. A write scope implies read of the same resource.

````

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