> ## 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. # Create API key > Creates a new API key for the current user ## OpenAPI ````yaml https://api.gumnut.ai/openapi.json post /api/api-keys/ 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. 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 the same filters as asset listing. - 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: 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/api-keys/: post: tags: - api-keys summary: Create API key description: Creates a new API key for the current user operationId: create_api_key requestBody: content: application/json: schema: $ref: '#/components/schemas/APIKeyCreateRequest' required: true responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/APIKeyCreateResponse' '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' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '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' security: - clerkSession: [] components: schemas: APIKeyCreateRequest: properties: name: type: string maxLength: 255 title: Name description: Descriptive name identifying this API key actions: items: $ref: '#/components/schemas/GrantAction' type: array title: Actions description: >- Action verbs the key may perform (at least one). `read` is required whenever any broader action is selected. Pass all four actions for a full-access key. library_scope_mode: $ref: '#/components/schemas/LibraryScopeMode' description: >- Which libraries the key covers: `all_libraries` (all current and future libraries) or `selected_libraries`. library_ids: anyOf: - items: type: string type: array maxItems: 200 - type: 'null' title: Library Ids description: >- Libraries the key covers. Required (at least one) when `library_scope_mode` is `selected_libraries`; not allowed otherwise. Up to 200 ids. type: object required: - name - actions - library_scope_mode title: APIKeyCreateRequest description: |- Create a key with an explicit action/library scope. The scope fields are required: a request must state both which actions the key may perform and which libraries it covers; omitting either is a 422, never a silent full-access grant. Full access is still expressible, but only explicitly: `actions=[read, write, delete, delete_permanently]` plus `library_scope_mode=all_libraries`. APIKeyCreateResponse: properties: id: type: string title: Id description: Unique API key identifier with 'apikey_' prefix name: anyOf: - type: string - type: 'null' title: Name description: Optional descriptive name for this API key created_at: type: string format: date-time title: Created At description: When this API key was created last_used_at: anyOf: - type: string format: date-time - type: 'null' title: Last Used At description: When this API key was last used for authentication is_active: type: boolean title: Is Active description: Whether this API key is currently valid and can be used actions: anyOf: - items: $ref: '#/components/schemas/GrantAction' type: array - type: 'null' title: Actions description: Action verbs this key's grant allows; null for legacy keys library_scope_mode: anyOf: - $ref: '#/components/schemas/LibraryScopeMode' - type: 'null' description: '''all_libraries'' or ''selected_libraries''; null for legacy keys' selected_library_count: anyOf: - type: integer - type: 'null' title: Selected Library Count description: >- Number of libraries a 'selected_libraries' grant covers; null unless library_scope_mode is 'selected_libraries' api_key: type: string title: Api Key description: >- The actual API key value - store this securely as it cannot be retrieved later type: object required: - id - created_at - is_active - api_key title: APIKeyCreateResponse description: |- Response when creating a new API key - includes the actual key value. This is the only time the raw API key is exposed. After creation, only the hashed version is stored and the raw key cannot be retrieved. ErrorResponse: title: ErrorResponse type: object properties: detail: title: Detail type: string description: Human-readable explanation of the error. required: - detail HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError GrantAction: type: string enum: - read - write - delete - delete_permanently title: GrantAction description: >- Actions a credential may perform. `read` views resources; `write` creates or changes them; `delete` trashes photos or libraries and destructively removes organizational records and associations such as albums, people, faces, and memberships; `delete_permanently` irreversibly deletes photos or libraries. LibraryScopeMode: type: string enum: - all_libraries - selected_libraries title: LibraryScopeMode description: >- Which of the owner's libraries a credential covers. `all_libraries` means all current and future live libraries owned by the user. `selected_libraries` means only explicitly selected libraries, with no automatic expansion. 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 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, so these operations are not callable with the credentials this API otherwise accepts. ````