openapi: 3.1.0
info:
  title: Sketchfab Data API
  description: >
    The Sketchfab Data API v3 provides programmatic read and write access to
    Sketchfab content. Authenticated callers can upload new 3D models, edit
    model metadata and settings, manage collections, comments, likes, and
    bookmarks, search the public model catalog, and administer organizations
    and projects. Public endpoints (model search, model detail, user profile)
    are available without authentication.
  version: v3
  contact:
    name: Sketchfab Developer Support
    url: https://support.fab.com/s/?ProductOrigin=Sketchfab
  license:
    name: Sketchfab Developer Terms of Use
    url: https://sketchfab.com/developers/terms
servers:
  - url: https://api.sketchfab.com
    description: Production API
security:
  - OAuth2: []
  - ApiTokenAuth: []
tags:
  - name: Models
    description: Manage 3D models — upload, list, retrieve, update, delete.
  - name: Search
    description: Search public Sketchfab content.
  - name: Users
    description: Retrieve user account information.
  - name: Collections
    description: Group models into themed collections.
  - name: Comments
    description: Comments on a model.
  - name: Likes
    description: Likes (favorites) on a model.
  - name: Bookmarks
    description: Personal bookmarks.
  - name: Categories
    description: Public Sketchfab category taxonomy.
  - name: Tags
    description: Tag-based discovery.
  - name: Orgs
    description: Organization, project, and member management.
paths:
  /v3/models:
    get:
      summary: Search 3D Models
      description: Search the public catalog of 3D models with full-text query, tags, categories, license, downloadable filter, and sort options.
      operationId: searchModels
      tags:
        - Models
        - Search
      parameters:
        - name: q
          in: query
          description: Full-text search query.
          schema:
            type: string
        - name: tags
          in: query
          description: Comma-separated list of tag slugs.
          schema:
            type: string
        - name: categories
          in: query
          description: Comma-separated list of category slugs.
          schema:
            type: string
        - name: downloadable
          in: query
          description: Restrict to downloadable models.
          schema:
            type: boolean
        - name: license
          in: query
          description: License filter (e.g. by, by-sa, cc0, ed, st).
          schema:
            type: string
        - name: sort_by
          in: query
          description: Sort order (-publishedAt, -likeCount, -viewCount, -processedAt).
          schema:
            type: string
        - name: cursor
          in: query
          description: Pagination cursor returned by previous response.
          schema:
            type: string
      responses:
        '200':
          description: Paginated list of models.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelList'
    post:
      summary: Upload A Model
      description: Create a new model from an uploaded 3D asset. Send multipart/form-data with the model file and metadata fields. Returns a model uid that can be polled until processing completes.
      operationId: uploadModel
      tags:
        - Models
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - modelFile
                - name
              properties:
                modelFile:
                  type: string
                  format: binary
                  description: The 3D model archive (zip) or single supported file.
                name:
                  type: string
                description:
                  type: string
                tags:
                  type: string
                  description: Space- or comma-separated tags.
                categories:
                  type: string
                  description: Comma-separated category slugs.
                license:
                  type: string
                  description: License slug (e.g. cc-by, cc-by-sa, cc0, st).
                private:
                  type: boolean
                password:
                  type: string
                isPublished:
                  type: boolean
                source:
                  type: string
                  description: Source application identifier (e.g. blender-exporter).
      responses:
        '201':
          description: Model created and queued for processing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  uid:
                    type: string
                  uri:
                    type: string
                    format: uri
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
  /v3/models/{uid}:
    get:
      summary: Retrieve A Model
      description: Get the public detail record for a single model — metadata, viewer URL, embed URL, thumbnails, and download availability.
      operationId: getModel
      tags:
        - Models
      parameters:
        - $ref: '#/components/parameters/ModelUid'
      responses:
        '200':
          description: Model detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '404':
          $ref: '#/components/responses/Error'
    patch:
      summary: Update A Model
      description: Update editable fields on a model owned by the authenticated user (name, description, tags, categories, license, private flag, password, publish state).
      operationId: updateModel
      tags:
        - Models
      parameters:
        - $ref: '#/components/parameters/ModelUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModelUpdate'
      responses:
        '204':
          description: Model updated.
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
    delete:
      summary: Delete A Model
      description: Permanently delete a model owned by the authenticated user.
      operationId: deleteModel
      tags:
        - Models
      parameters:
        - $ref: '#/components/parameters/ModelUid'
      responses:
        '204':
          description: Model deleted.
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
  /v3/models/{uid}/comments:
    get:
      summary: List Model Comments
      description: Retrieve comments posted on a model.
      operationId: listModelComments
      tags:
        - Comments
      parameters:
        - $ref: '#/components/parameters/ModelUid'
      responses:
        '200':
          description: Comment list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Comment'
  /v3/models/{uid}/likes:
    post:
      summary: Like A Model
      description: Like the model on behalf of the authenticated user.
      operationId: likeModel
      tags:
        - Likes
      parameters:
        - $ref: '#/components/parameters/ModelUid'
      responses:
        '201':
          description: Like created.
        '401':
          $ref: '#/components/responses/Error'
    delete:
      summary: Unlike A Model
      description: Remove the authenticated user's like for the model.
      operationId: unlikeModel
      tags:
        - Likes
      parameters:
        - $ref: '#/components/parameters/ModelUid'
      responses:
        '204':
          description: Like removed.
  /v3/me:
    get:
      summary: Retrieve The Current User
      description: Get the authenticated user's profile, plan, and account metadata.
      operationId: getCurrentUser
      tags:
        - Users
      responses:
        '200':
          description: Authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Error'
  /v3/users/{username}:
    get:
      summary: Retrieve A User
      description: Public profile for the requested user.
      operationId: getUser
      tags:
        - Users
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /v3/collections:
    get:
      summary: List Collections
      description: List collections for the authenticated user or for the user filter.
      operationId: listCollections
      tags:
        - Collections
      parameters:
        - name: user
          in: query
          schema:
            type: string
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Collection list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionList'
    post:
      summary: Create A Collection
      description: Create a new collection of models.
      operationId: createCollection
      tags:
        - Collections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                description:
                  type: string
                isPrivate:
                  type: boolean
      responses:
        '201':
          description: Collection created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
  /v3/collections/{uid}/models:
    post:
      summary: Add A Model To A Collection
      description: Add a model to the specified collection.
      operationId: addModelToCollection
      tags:
        - Collections
      parameters:
        - name: uid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - models
              properties:
                models:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: Model(s) added.
  /v3/search:
    get:
      summary: Search Sketchfab
      description: Unified search across models, collections, and users with a `type` selector.
      operationId: search
      tags:
        - Search
      parameters:
        - name: type
          in: query
          description: One of `models`, `collections`, or `users`.
          schema:
            type: string
            enum:
              - models
              - collections
              - users
        - name: q
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Search results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
  /v3/categories:
    get:
      summary: List Categories
      description: Public Sketchfab category taxonomy.
      operationId: listCategories
      tags:
        - Categories
      responses:
        '200':
          description: Category list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Category'
  /v3/tags:
    get:
      summary: List Tags
      description: Discover popular and matching tags.
      operationId: listTags
      tags:
        - Tags
      parameters:
        - name: q
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Tag list.
  /v3/me/bookmarks:
    get:
      summary: List My Bookmarks
      description: Retrieve the authenticated user's bookmarked models.
      operationId: listBookmarks
      tags:
        - Bookmarks
      responses:
        '200':
          description: Bookmark list.
  /v3/orgs/{org}:
    get:
      summary: Retrieve An Organization
      description: Get organization detail, including plan and member count, for organizations the caller belongs to.
      operationId: getOrg
      tags:
        - Orgs
      parameters:
        - name: org
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Organization detail.
  /v3/orgs/{org}/projects:
    get:
      summary: List Organization Projects
      description: List projects (workspaces) within an organization.
      operationId: listOrgProjects
      tags:
        - Orgs
      parameters:
        - name: org
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Project list.
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: Sketchfab OAuth 2.0. Access tokens are valid for one month.
      flows:
        authorizationCode:
          authorizationUrl: https://sketchfab.com/oauth2/authorize/
          tokenUrl: https://sketchfab.com/oauth2/token/
          refreshUrl: https://sketchfab.com/oauth2/token/
          scopes:
            read: Read access to the caller's account, models, and collections.
            write: Create, update, and delete the caller's models and collections.
    ApiTokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Personal API token sent as `Authorization: Token <token>`.
  parameters:
    ModelUid:
      name: uid
      in: path
      required: true
      description: Sketchfab model UID (hex string in the URL after /models/).
      schema:
        type: string
  responses:
    Error:
      description: Error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Model:
      type: object
      properties:
        uid:
          type: string
        uri:
          type: string
          format: uri
        name:
          type: string
        description:
          type: string
        viewerUrl:
          type: string
          format: uri
        embedUrl:
          type: string
          format: uri
        thumbnails:
          type: object
        tags:
          type: array
          items:
            type: object
            properties:
              slug:
                type: string
              name:
                type: string
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
        license:
          type: object
          properties:
            slug:
              type: string
            label:
              type: string
            uri:
              type: string
        user:
          $ref: '#/components/schemas/User'
        isDownloadable:
          type: boolean
        animationCount:
          type: integer
        vertexCount:
          type: integer
        faceCount:
          type: integer
        viewCount:
          type: integer
        likeCount:
          type: integer
        commentCount:
          type: integer
        publishedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
    ModelUpdate:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        tags:
          type: array
          items:
            type: string
        categories:
          type: array
          items:
            type: string
        license:
          type: string
        private:
          type: boolean
        password:
          type: string
        isPublished:
          type: boolean
    ModelList:
      type: object
      properties:
        cursors:
          type: object
          properties:
            next:
              type: string
              nullable: true
            previous:
              type: string
              nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/Model'
    User:
      type: object
      properties:
        uid:
          type: string
        username:
          type: string
        displayName:
          type: string
        profileUrl:
          type: string
          format: uri
        account:
          type: string
          description: Plan slug (basic, plus, pro, premium, business, enterprise).
        avatar:
          type: object
    Comment:
      type: object
      properties:
        uid:
          type: string
        body:
          type: string
        user:
          $ref: '#/components/schemas/User'
        createdAt:
          type: string
          format: date-time
    Collection:
      type: object
      properties:
        uid:
          type: string
        name:
          type: string
        description:
          type: string
        modelCount:
          type: integer
        embedUrl:
          type: string
          format: uri
        user:
          $ref: '#/components/schemas/User'
    CollectionList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Collection'
    Category:
      type: object
      properties:
        slug:
          type: string
        name:
          type: string
        uri:
          type: string
          format: uri
    Error:
      type: object
      properties:
        detail:
          type: string
        code:
          type: string