openapi: 3.0.3
info:
  title: ImageKit Account Management API URL endpoints API
  version: 1.0.0
  description: Checkout [API overview](/docs/api-overview) to learn about ImageKit's APIs, authentication, rate limits, and error codes etc.
  contact:
    email: developer@imagekit.io
    name: ImageKit Team
    url: https://imagekit.io
  termsOfService: https://imagekit.io/terms/
servers:
- url: https://api.imagekit.io
security:
- basicAuth: []
tags:
- name: URL endpoints
paths:
  /v1/accounts/url-endpoints:
    get:
      summary: List URL‑endpoints
      tags:
      - URL endpoints
      operationId: list-url-endpoints
      description: "**Note:** This API is currently in beta.  \nReturns an array of all URL‑endpoints configured including the default URL-endpoint generated by ImageKit during account creation.\n"
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UrlEndpointResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                    - URL-endpoint not found.
                  help:
                    type: string
                    example: For support kindly contact us at support@imagekit.io.
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    post:
      summary: Create URL‑endpoint
      tags:
      - URL endpoints
      operationId: create-url-endpoint
      description: "**Note:** This API is currently in beta.  \nCreates a new URL‑endpoint and returns the resulting object.\n"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UrlEndpointRequest'
      responses:
        '201':
          description: URL‑endpoint created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UrlEndpointResponse'
        '400':
          description: Bad request. The request body is invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                    - description is required
                    - urlPrefix must be a string
                    - urlPrefix cannot be empty string. This is reserved for the default URL-endpoint created by ImageKit.
                    - Origin does not exists. Please create origin before using it in URL-endpoint.
                  help:
                    type: string
                    example: For support kindly contact us at support@imagekit.io.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /v1/accounts/url-endpoints/{id}:
    get:
      summary: Get URL‑endpoint
      tags:
      - URL endpoints
      operationId: get-url-endpoint
      description: "**Note:** This API is currently in beta.  \nRetrieves the URL‑endpoint identified by `id`.\n"
      parameters:
      - in: path
        name: id
        schema:
          description: Unique identifier for the URL-endpoint. This is generated by ImageKit when you create a new URL-endpoint. For the default URL-endpoint, this is always `default`.
          type: string
        required: true
        description: Unique identifier for the URL-endpoint. This is generated by ImageKit when you create a new URL-endpoint. For the default URL-endpoint, this is always `default`.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UrlEndpointResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                    - URL-endpoint not found.
                  help:
                    type: string
                    example: For support kindly contact us at support@imagekit.io.
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    put:
      summary: Update URL‑endpoint
      tags:
      - URL endpoints
      operationId: update-url-endpoint
      description: "**Note:** This API is currently in beta.  \nUpdates the URL‑endpoint identified by `id` and returns the updated object.\n"
      parameters:
      - in: path
        name: id
        schema:
          description: Unique identifier for the URL-endpoint. This is generated by ImageKit when you create a new URL-endpoint. For the default URL-endpoint, this is always `default`.
          type: string
        required: true
        description: Unique identifier for the URL-endpoint. This is generated by ImageKit when you create a new URL-endpoint. For the default URL-endpoint, this is always `default`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UrlEndpointRequest'
      responses:
        '200':
          description: URL‑endpoint updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UrlEndpointResponse'
        '400':
          description: Bad request. The request body is invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                    - description is required
                    - urlPrefix must be a string
                    - urlPrefix cannot be empty string. This is reserved for the default URL-endpoint created by ImageKit.
                    - Origin does not exists. Please create origin before using it in URL-endpoint.
                  help:
                    type: string
                    example: For support kindly contact us at support@imagekit.io.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                    - URL-endpoint not found.
                  help:
                    type: string
                    example: For support kindly contact us at support@imagekit.io.
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    delete:
      summary: Delete URL‑endpoint
      tags:
      - URL endpoints
      operationId: delete-url-endpoint
      description: "**Note:** This API is currently in beta.  \nDeletes the URL‑endpoint identified by `id`. You cannot delete the default URL‑endpoint created by ImageKit during account creation.\n"
      parameters:
      - in: path
        name: id
        schema:
          description: Unique identifier for the URL-endpoint. This is generated by ImageKit when you create a new URL-endpoint. For the default URL-endpoint, this is always `default`.
          type: string
        required: true
        description: Unique identifier for the URL-endpoint. This is generated by ImageKit when you create a new URL-endpoint. For the default URL-endpoint, this is always `default`.
      responses:
        '204':
          description: URL‑endpoint deleted successfully.
        '400':
          description: Bad request. The request body is invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                    - Default URL-endpoint cannot be deleted.
                  help:
                    type: string
                    example: For support kindly contact us at support@imagekit.io.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                    - URL-endpoint not found.
                  help:
                    type: string
                    example: For support kindly contact us at support@imagekit.io.
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
components:
  responses:
    Forbidden:
      description: Forbidden.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                examples:
                - Your account cannot be authenticated.
                - Your request contains expired private API key.
                - Your account is disabled.
              help:
                type: string
                example: For support kindly contact us at support@imagekit.io.
    Unauthorized:
      description: Unauthorized request.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Your request does not contain private API key.
              help:
                type: string
                example: For support kindly contact us at support@imagekit.io.
    RateLimitExceeded:
      description: The request exceeded the rate limit. Contains headers indicating the limits and a message detailing the error.
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
          description: The maximum number of requests that can be made to this endpoint in the interval specified by `X-RateLimit-Interval` response header.
        X-RateLimit-Reset:
          schema:
            type: integer
          description: The amount of time in milliseconds before you can make another request to this endpoint. Pause/sleep your workflow for this duration.
        X-RateLimit-Interval:
          schema:
            type: integer
          description: The duration of the interval in milliseconds for which this rate limit was exceeded.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: A description of the error, providing details about why the rate limit has been exceeded.
  schemas:
    UrlEndpointResponse:
      title: URL‑endpoint Response
      description: URL‑endpoint object as returned by the API.
      type: object
      properties:
        description:
          description: Description of the URL endpoint.
          example: My custom URL endpoint
          type: string
          minLength: 1
          maxLength: 1000
        urlPrefix:
          description: Path segment appended to your base URL to form the endpoint (letters, digits, and hyphens only — or empty for the default endpoint).
          example: product-images
          default: ''
          type: string
          maxLength: 100
        origins:
          description: Ordered list of origin IDs to try when the file isn’t in the Media Library; ImageKit checks them in the sequence provided. Origin must be created before it can be used in a URL endpoint.
          example:
          - origin-id-1
          - origin-id-2
          default: []
          maxItems: 10
          type: array
          items:
            description: Unique identifier for the origin. This is generated by ImageKit when you create a new origin.
            type: string
        urlRewriter:
          description: Configuration for third-party URL rewriting.
          discriminator:
            propertyName: type
          oneOf:
          - title: Cloudinary URL Rewriter
            type: object
            properties:
              type:
                type: string
                enum:
                - CLOUDINARY
              preserveAssetDeliveryTypes:
                description: Whether to preserve `<asset_type>/<delivery_type>` in the rewritten URL.
                example: true
                default: false
                type: boolean
            required:
            - type
            - preserveAssetDeliveryTypes
            additionalProperties: false
          - title: Imgix URL Rewriter
            type: object
            properties:
              type:
                type: string
                enum:
                - IMGIX
            required:
            - type
            additionalProperties: false
          - title: Akamai URL Rewriter
            type: object
            properties:
              type:
                type: string
                enum:
                - AKAMAI
            required:
            - type
            additionalProperties: false
          type: object
        id:
          readOnly: true
          description: Unique identifier for the URL-endpoint. This is generated by ImageKit when you create a new URL-endpoint. For the default URL-endpoint, this is always `default`.
          type: string
      required:
      - description
      - urlPrefix
      - origins
      - id
      additionalProperties: false
    UrlEndpointRequest:
      title: URL Endpoint Schema
      description: Schema for URL endpoint resource.
      example:
        description: My custom URL endpoint
        urlPrefix: product-images
        origins:
        - origin-id-1
      type: object
      properties:
        description:
          description: Description of the URL endpoint.
          example: My custom URL endpoint
          type: string
          minLength: 1
          maxLength: 1000
        urlPrefix:
          description: Path segment appended to your base URL to form the endpoint (letters, digits, and hyphens only — or empty for the default endpoint).
          example: product-images
          default: ''
          type: string
          maxLength: 100
        origins:
          description: Ordered list of origin IDs to try when the file isn’t in the Media Library; ImageKit checks them in the sequence provided. Origin must be created before it can be used in a URL endpoint.
          example:
          - origin-id-1
          - origin-id-2
          default: []
          maxItems: 10
          type: array
          items:
            description: Unique identifier for the origin. This is generated by ImageKit when you create a new origin.
            type: string
        urlRewriter:
          description: Configuration for third-party URL rewriting.
          discriminator:
            propertyName: type
          oneOf:
          - title: Cloudinary URL Rewriter
            type: object
            properties:
              type:
                type: string
                enum:
                - CLOUDINARY
              preserveAssetDeliveryTypes:
                description: Whether to preserve `<asset_type>/<delivery_type>` in the rewritten URL.
                example: true
                default: false
                type: boolean
            required:
            - type
            additionalProperties: false
          - title: Imgix URL Rewriter
            type: object
            properties:
              type:
                type: string
                enum:
                - IMGIX
            required:
            - type
            additionalProperties: false
          - title: Akamai URL Rewriter
            type: object
            properties:
              type:
                type: string
                enum:
                - AKAMAI
            required:
            - type
            additionalProperties: false
          type: object
      required:
      - description
      additionalProperties: false
  securitySchemes:
    basicAuth:
      description: 'Basic HTTP authentication. Allowed headers-- Authorization: Basic <private_api_key> | Authorization: Basic <base64 hash of `private_api_key:`>

        ImageKit API uses API keys to authenticate requests. You can view and manage your API keys in [the dashboard](https://imagekit.io/dashboard/developer/api-keys).

        All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.'
      scheme: basic
      type: http