> ## Documentation Index > Fetch the complete documentation index at: https://docs.gumnut.ai/llms.txt > Use this file to discover all available pages before exploring further. # Join a library through an invitation > Admit the caller atomically or return their unchanged existing access. Retrying an uncertain join unchanged consumes no additional place. Invalid secrets or unavailable libraries return a generic 404; retry with a valid, available link. Expired, disabled, exhausted, or removal-cutoff invitations return 409; request a new invitation. Admission disabled returns 503; retry after it becomes available. ## OpenAPI ````yaml https://api.gumnut.ai/openapi.json post /api/libraries/invitations/{invitation_id}/join openapi: 3.1.0 info: title: Gumnut API description: >- The Gumnut API manages photo and video libraries: upload and organize assets, search by content, group detected faces into people, and curate albums and stacks. Headless clients authenticate by sending either a Gumnut API key (`apikey_...`) or an OAuth access token as a Bearer token in the `Authorization` header. The Gumnut web and mobile apps sign in with a first-party session (Clerk session JWT) instead, which is also the only credential that can manage API keys and library sharing. contact: name: Gumnut url: https://www.gumnut.ai/contact version: 1.0.0 servers: - url: https://api.gumnut.ai description: Production security: - apiKeyAuth: [] - oauthJwtAuth: [] tags: - name: assets description: >- Photos and videos in a library: upload, list and filter, update metadata, trash and restore. - name: search description: >- Content-based search over a library's assets, with album, person, date, and location filters. - name: albums description: User-curated collections of assets. - name: album-assets description: Link records connecting albums to their member assets. - name: stacks description: >- Groups of related shots of the same moment, presented as a single unit with a cover asset. - name: people description: Named people, each built from clustered faces. - name: faces description: Detected faces and their assignment to people. - name: libraries description: Top-level containers that own assets, albums, people, and everything else. - name: library-invitations description: First-party invitation management and admission for photo libraries. - name: events description: Change-event feed for keeping client state in sync. - name: tasks description: Status of background processing tasks. - name: users description: The authenticated user's profile. - name: api-keys description: >- Create and manage Gumnut API keys. Requires a first-party Gumnut app session — API keys and OAuth tokens cannot manage credentials. - name: oauth description: OAuth flow endpoints for obtaining and refreshing access tokens. - name: server description: Service health. paths: /api/libraries/invitations/{invitation_id}/join: post: tags: - library-invitations summary: Join a library through an invitation description: >- Admit the caller atomically or return their unchanged existing access. Retrying an uncertain join unchanged consumes no additional place. Invalid secrets or unavailable libraries return a generic 404; retry with a valid, available link. Expired, disabled, exhausted, or removal-cutoff invitations return 409; request a new invitation. Admission disabled returns 503; retry after it becomes available. operationId: join_library_invitation parameters: - name: invitation_id in: path required: true schema: type: string description: Invitation identifier. title: Invitation Id description: Invitation identifier. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InvitationSecretRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/InvitationJoinResponse' '401': description: Missing, invalid, or expired credentials. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- The credentials are valid but not authorized for this operation — for example an API key whose action or library scope excludes it, or a credential type this operation does not accept. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- `invitation_unavailable`: invitation is unavailable. Retry only with a valid, available invitation link. content: application/json: schema: $ref: '#/components/schemas/SharingErrorResponse' '409': description: >- `invitation_expired`, `invitation_disabled`, `invitation_exhausted`, or `new_invitation_required`: invitation cannot admit this account. Retrying unchanged will not clear the conflict; request a new invitation. Clerk sign-in could not be associated with the existing account. Resolve the identity conflict before retrying sign-in; repeated requests with unchanged verification and identity state will not resolve it. content: application/json: schema: anyOf: - $ref: '#/components/schemas/ErrorResponse' - $ref: '#/components/schemas/SharingErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityResponse' '429': description: >- Rate limit exceeded. Retry after the interval in the `Retry-After` header. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- `admission_disabled`: invitation admission is disabled; retry after it becomes available. Authentication provider outages also return 503; retry sign-in later. content: application/json: schema: anyOf: - $ref: '#/components/schemas/ErrorResponse' - $ref: '#/components/schemas/SharingErrorResponse' security: - clerkSession: [] components: schemas: InvitationSecretRequest: properties: secret: type: string maxLength: 64 minLength: 1 format: password title: Secret description: Opaque secret from the invitation URL fragment. writeOnly: true type: object required: - secret title: InvitationSecretRequest InvitationJoinResponse: properties: outcome: type: string enum: - joined - already_member title: Outcome description: >- Whether this request admitted the account or returned unchanged access. library: $ref: '#/components/schemas/LibraryResponse' description: Library context with the caller's actual role. membership: anyOf: - $ref: '#/components/schemas/MembershipResponse' - type: 'null' description: >- Active non-owner membership; null only when the caller owns the library. type: object required: - outcome - library - membership title: InvitationJoinResponse ErrorResponse: title: ErrorResponse type: object properties: detail: title: Detail type: string description: Human-readable explanation of the error. required: - detail SharingErrorResponse: title: SharingErrorResponse type: object properties: detail: type: string description: Human-readable explanation of the library-sharing failure. code: type: string description: Stable library-sharing failure code. required: - detail - code UnprocessableEntityResponse: title: UnprocessableEntityResponse type: object properties: detail: title: Detail description: >- A semantic validation message or structured request-validation errors. oneOf: - type: string description: Human-readable semantic validation message. - type: array items: $ref: '#/components/schemas/ValidationError' description: Structured request-validation errors. required: - detail LibraryResponse: properties: id: type: string title: Id description: Unique library identifier with 'lib_' prefix name: type: string title: Name description: Display name of the library description: anyOf: - type: string - type: 'null' title: Description description: Optional description text for the library user_id: type: string title: User Id description: ID of the user who owns this library owner: $ref: '#/components/schemas/UserSummary' role: type: string enum: - owner - viewer - collaborator title: Role asset_count: type: integer title: Asset Count description: Total number of assets in this library storage_used_bytes: type: integer title: Storage Used Bytes description: Bytes of assets currently stored in this library storage_limit_bytes: anyOf: - type: integer - type: 'null' title: Storage Limit Bytes description: >- Maximum bytes this library may store, or null if no per-library limit applies created_at: type: string format: date-time title: Created At description: When this library was created updated_at: type: string format: date-time title: Updated At description: When this library was last updated type: object required: - id - name - user_id - owner - role - asset_count - storage_used_bytes - created_at - updated_at title: LibraryResponse description: Represents a user's photo library. MembershipResponse: properties: id: type: string title: Id description: Stable membership record identifier. library_id: type: string title: Library Id description: Library this membership belongs to. user: $ref: '#/components/schemas/UserSummary' description: Member account summary. role: $ref: '#/components/schemas/LibraryMemberRole' description: Current or last assigned role. state: $ref: '#/components/schemas/LibraryMembershipState' joined_at: type: string format: date-time title: Joined At description: Most recent admission instant. ended_at: anyOf: - type: string format: date-time - type: 'null' title: Ended At description: Most recent departure or removal instant, or null while active. last_removed_at: anyOf: - type: string format: date-time - type: 'null' title: Last Removed At description: Retained owner-removal cutoff for readmission, or null. created_at: type: string format: date-time title: Created At description: When this record was created. updated_at: type: string format: date-time title: Updated At description: When this record last changed. type: object required: - id - library_id - user - role - state - joined_at - ended_at - last_removed_at - created_at - updated_at title: MembershipResponse ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError UserSummary: properties: id: type: string title: Id description: User identifier display_name: anyOf: - type: string - type: 'null' title: Display Name description: Public display name, when available type: object required: - id - display_name title: UserSummary LibraryMemberRole: type: string enum: - viewer - collaborator title: LibraryMemberRole description: >- Non-owner library permissions. viewer reads library content. collaborator also edits and organizes content, including trash and restore. Neither administers members or permanently deletes photos. LibraryMembershipState: type: string enum: - active - left - removed title: LibraryMembershipState description: |- A member's library access state. active grants the assigned role. left means the member departed; removed means the owner revoked access. left and removed grant no access. securitySchemes: apiKeyAuth: type: http scheme: bearer description: >- Gumnut API key (`apikey_...`) sent as a Bearer token in the `Authorization` header. Create and manage keys in the Gumnut app, or with the API key endpoints while signed in to it. oauthJwtAuth: type: http scheme: bearer bearerFormat: JWT description: >- Short-lived JWT obtained from the OAuth token exchange, sent as a Bearer token in the `Authorization` header. clerkSession: type: http scheme: bearer bearerFormat: JWT description: >- First-party Gumnut app session (Clerk session JWT). Only the Gumnut web and mobile apps can obtain one — API keys and OAuth tokens cannot manage credentials or library sharing, so these operations are not callable with the credentials this API otherwise accepts. ````