Autodesk Objects API

openapi: 3.2.0
info:
  title: oss Objects API
  version: '1.0'
  description: The Object Storage Service (OSS) allows your application to download and upload raw files (such as PDF, XLS, DWG, or RVT) that are managed by the Data service.
  contact:
    name: Autodesk Platform Services
    url: https://aps.autodesk.com/
    email: aps.help@autodesk.com
  termsOfService: https://www.autodesk.com/company/legal-notices-trademarks/terms-of-service-autodesk360-web-services/forge-platform-web-services-api-terms-of-service
  x-support: https://stackoverflow.com/questions/tagged/autodesk-data-management
servers:
- url: https://developer.api.autodesk.com
tags:
- name: Objects
  description: Object related operations
paths:
  /oss/v2/buckets/{bucketKey}/objects/{objectKey}:
    delete:
      tags:
      - Objects
      summary: Delete Object
      description: Deletes the specified object from the bucket.
      operationId: deleteObject
      parameters:
      - $ref: '#/components/parameters/bucketKey'
      - $ref: '#/components/parameters/objectKey'
      responses:
        '200':
          description: The object was successfully deleted.
          content: {}
        '400':
          $ref: '#/components/responses/BAD_REQUEST'
        '401':
          $ref: '#/components/responses/UNAUTHORIZED'
        '403':
          $ref: '#/components/responses/FORBIDDEN'
        '404':
          description: The specified ``bucketKey`` or ``objectKey`` does not exist.
          content: {}
        '500':
          $ref: '#/components/responses/INTERNAL_SERVER_ERROR'
      security:
      - 2-legged:
        - data:write
      x-codeSamples:
      - lang: cURL
        source: 'curl -v "https://developer.api.autodesk.com/oss/v2/buckets/bucketexamplekey/objects/objectKey" -X DELETE -H "Authorization: Bearer kuhodzPEHSCrWH3Pm1WuBMBnxw39" -H "Content-Type: application/json;charset=UTF-8"'
  /oss/v2/buckets/{bucketKey}/objects:
    get:
      tags:
      - Objects
      summary: List Objects
      description: 'Retrieves a list of objects in the specified bucket.


        Only the application that owns the bucket can call this operation. All other applications that call this operation will receive a "403 Forbidden" error.'
      operationId: getObjects
      parameters:
      - $ref: '#/components/parameters/bucketKey'
      - $ref: '#/components/parameters/limit'
      - name: beginsWith
        in: query
        description: Filters the results by the value you specify. Only the objects with their ``objectKey`` beginning with the specified string are returned.
        schema:
          type: string
      - $ref: '#/components/parameters/startAt'
      responses:
        '200':
          description: The requested objects were successfully retrieved.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/BucketObjectsPage'
            application/json:
              examples:
                success:
                  summary: Successful object list (200)
                  value:
                    items:
                    - bucketKey: apptestbucket
                      objectKey: objectKeyFoo
                      objectId: urn:adsk.objects:os.object:apptestbucket/objectKeyFoo
                      sha1: cdbf71bfc07cbc18372a5dd4b6e161463cb7fd35
                      size: 7
                      location: https://developer.api.autodesk.com/oss/v2/buckets/apptestbucket/objects/objectKeyFoo
                    next: https://developer.api.autodesk.com/oss/v2/buckets/apptestbucket/objects?startAt=objectKeyFoo&limit=1
              schema:
                $ref: '#/components/schemas/BucketObjectsPage'
        '400':
          $ref: '#/components/responses/BAD_REQUEST'
        '401':
          $ref: '#/components/responses/UNAUTHORIZED'
        '403':
          $ref: '#/components/responses/FORBIDDEN'
        '500':
          $ref: '#/components/responses/INTERNAL_SERVER_ERROR'
      security:
      - 2-legged:
        - data:read
      x-codeSamples:
      - lang: cURL
        source: 'curl -v "https://developer.api.autodesk.com/oss/v2/buckets/apptestbucket/objects?limit=1" -X GET -H "Authorization: Bearer ShiAeQ67rdNSfmyEmtGW8Lnrcqto" -H "Content-Type: application/json"'
  /oss/v2/buckets/{bucketKey}/objects/{objectKey}/details:
    get:
      tags:
      - Objects
      summary: Get Object Details
      description: Retrieves detailed information about the specified object.
      operationId: getObjectDetails
      parameters:
      - $ref: '#/components/parameters/bucketKey'
      - $ref: '#/components/parameters/objectKey'
      - $ref: '#/components/parameters/If-Modified-Since'
      - $ref: '#/components/parameters/with'
      responses:
        '200':
          description: The object details were successfully retrieved.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ObjectFullDetails'
            application/json:
              examples:
                success:
                  summary: Get Object Details - Success (200)
                  value:
                    bucketKey: apptestbucket
                    objectId: urn:adsk.objects:os.object:apptestbucket/test.txt
                    objectKey: test.txt
                    sha1: 33a16388013ce310564af70b0ef5320d8fd85444
                    size: 618
                    contentType: application/x-www-form-urlencoded
                    location: https://developer.api.autodesk.com/oss/v2/buckets/apptestbucket/objects/test.txt
                    blockSizes:
                    - 2048
              schema:
                $ref: '#/components/schemas/ObjectFullDetails'
        '304':
          description: The object has not been modified since the specified date.
          content: {}
        '400':
          $ref: '#/components/responses/BAD_REQUEST'
        '401':
          $ref: '#/components/responses/UNAUTHORIZED'
        '403':
          $ref: '#/components/responses/FORBIDDEN'
        '404':
          description: The specified ``bucketKey`` or ``objectKey`` does not exist.
          content: {}
        '500':
          $ref: '#/components/responses/INTERNAL_SERVER_ERROR'
      security:
      - 2-legged:
        - data:read
      x-codeSamples:
      - lang: cURL
        source: 'curl -v "https://developer.api.autodesk.com/oss/v2/buckets/apptestbucket/objects/test.txt/details" -X GET -H "Authorization: Bearer ShiAeQ67rdNSfmyEmtGW8Lnrcqto" -H "Content-Type: application/json"'
  /oss/v2/buckets/{bucketKey}/objects/{objectKey}/copyto/{newObjName}:
    put:
      tags:
      - Objects
      summary: Copy Object
      description: Creates a copy of the specified object within the bucket.
      operationId: copyTo
      parameters:
      - $ref: '#/components/parameters/bucketKey'
      - $ref: '#/components/parameters/objectKey'
      - name: newObjName
        in: path
        description: A URL-encoded human friendly name to identify the copied object.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The object was successfully copied.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ObjectDetails'
            application/json:
              examples:
                success:
                  summary: Successful Copy Object (200)
                  value:
                    bucketKey: bucketexamplekey
                    objectId: urn:adsk.objects:os.object:bucketexamplekey/copyoftestobject
                    objectKey: copyoftestobject
                    sha1: cdbf71bfc07cbc18372a5dd4b6e161463cb7fd35
                    size: 7
                    contentType: text/plain; charset=UTF-8
                    location: https://developer.api.autodesk.com/oss/v2/buckets/bucketexamplekey/objects/copyoftestobject
              schema:
                $ref: '#/components/schemas/ObjectDetails'
        '400':
          $ref: '#/components/responses/BAD_REQUEST'
        '401':
          $ref: '#/components/responses/UNAUTHORIZED'
        '403':
          $ref: '#/components/responses/FORBIDDEN'
        '404':
          $ref: '#/components/responses/NOT_FOUND'
        '500':
          $ref: '#/components/responses/INTERNAL_SERVER_ERROR'
      security:
      - 2-legged:
        - data:write
        - data:create
      x-codeSamples:
      - lang: cURL
        source: 'curl -v "https://developer.api.autodesk.com/oss/v2/buckets/bucketexamplekey/objects/testobject/copyto/copyoftestobject" -X PUT -H "Authorization: Bearer 1B6FU8z9S2x1PrjADDfPCzSGrXmI"'
components:
  schemas:
    ObjectFullDetails:
      type: object
      description: Represents detailed information about an object within a bucket.
      properties:
        bucketKey:
          type: string
          description: The bucket key of the bucket that contains the object.
        objectId:
          type: string
          description: An identifier (URN) that uniquely and persistently identifies the object.
        objectKey:
          type: string
          description: A URL-encoded human-friendly name that identifies the object.
        sha1:
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
          type: string
          description: A hash value computed from the data of the object.
          format: byte
        size:
          type: integer
          description: The total amount of storage space occupied by the object, in bytes.
          format: int64
        contentType:
          type: string
          description: The format of the data stored within the object, expressed as a MIME type.
        location:
          type: string
          description: A URL that points to the actual location of the object.
        createdDate:
          type: integer
          format: int64
          description: The time the object was created, represented as a Unix timestamp. Only returned if explicitly requested using the ``with`` query string parameter.
        lastAccessedDate:
          type: integer
          format: int64
          description: The time the object was last accessed, represented as a Unix timestamp. Only returned if explicitly requested using the ``with`` query string parameter.
        lastModifiedDate:
          type: integer
          format: int64
          description: The time the object was most recently modified, represented as a Unix timestamp. Only returned if explicitly requested using the ``with`` query string parameter.
        userDefinedMetadata:
          type: string
          description: Any custom metadata, if available. Only returned if explicitly requested using the ``with`` query string parameter.
        blockSizes:
          type: array
          description: The sizes of the blocks the object is stored in, in bytes.
          items:
            type: integer
            format: int64
    With:
      title: With
      description: 'Possible values:


        - ``createdDate``

        - ``lastAccessedDate``

        - ``lastModifiedDate``

        - ``userDefinedMetadata``

        '
      type: string
      enum:
      - createdDate
      - lastAccessedDate
      - lastModifiedDate
      - userDefinedMetadata
    ObjectDetails:
      type: object
      properties:
        bucketKey:
          type: string
          description: The bucket key of the bucket that contains the object.
        objectId:
          type: string
          description: An identifier (URN) that uniquely and persistently identifies the object.
        objectKey:
          type: string
          description: A URL-encoded human-friendly name that identifies the object.
        sha1:
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
          type: string
          description: A hash value computed from the data of the object.
          format: byte
        size:
          type: integer
          description: The total amount of storage space occupied by the object, in bytes.
          format: int64
        contentType:
          type: string
          description: The format of the data stored within the object, expressed as a MIME type.
        location:
          type: string
          description: A URL that points to the actual location of the object.
      description: Represents an object within a bucket.
    BucketObjectsPage:
      type: object
      description: An array where each element represents an object in the bucket.
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ObjectDetails'
        next:
          type: string
          description: The URL to be used to retrieve the next page of results, if available. It will be present only when there are more items to be retrieved after the current set.
  responses:
    INTERNAL_SERVER_ERROR:
      description: An unexpected error occurred on the server, preventing it from completing your request. Please try again later. If the issue persists, contact the support team for assistance.
      content: {}
    BAD_REQUEST:
      description: OSS was unable to process the request. The syntax of the request is malformed or the request is missing a required header. Do not repeat the request without fixing the issue. The response body may indicate what is wrong with the request
      content: {}
    FORBIDDEN:
      description: The request was successfully validated but lacking the required permissions. Verify your credentials and permissions before you send this request again.
      content: {}
    UNAUTHORIZED:
      description: The supplied authorization header was not valid or the supplied token scope was not acceptable. Verify authentication and try again.
      content: {}
    NOT_FOUND:
      description: The requested resource could not be found. Verify the IDs of the resources you requested before you send this request again.
      content: {}
  parameters:
    with:
      name: with
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/With'
    limit:
      name: limit
      in: query
      description: 'The maximum number of items to return per page. This parameter controls pagination by limiting the size of each response. Acceptable values: 1-100. Default value: 10.

        '
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 100
    startAt:
      name: startAt
      in: query
      description: 'The ID of the last item from the previous result set. Use this parameter to retrieve the next page of results by starting from the item immediately following the specified ID.

        '
      schema:
        type: string
    objectKey:
      name: objectKey
      in: path
      description: The URL-encoded human friendly name of the object.
      required: true
      schema:
        type: string
    bucketKey:
      name: bucketKey
      in: path
      description: The unique ID of the bucket that contains the objects you are operating on. ``bucketKey`` must be URL-encoded.
      required: true
      schema:
        pattern: ^[-_.a-z0-9]{3,128}$
        type: string
    If-Modified-Since:
      name: If-Modified-Since
      in: header
      description: 'A timestamp in the HTTP date format (Mon, DD Month YYYY HH:MM:SS GMT). The requested data is returned only if the object has been modified since the specified timestamp. If not, a 304 (Not Modified) HTTP status is returned.

        '
      schema:
        type: string
        format: date
  securitySchemes:
    oauth2_application:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /authentication/v1/authenticate
          scopes:
            data:read: The application will be able to read the end user’s data within the Autodesk ecosystem.
            data:write: The application will be able to create, update, and delete data on behalf of the end user within the Autodesk ecosystem.
            data:create: The application will be able to create data on behalf of the end user within the Autodesk ecosystem.
            bucket:delete: The application will be able to delete an OSS bucket it will own.
            bucket:create: The application will be able to create an OSS bucket it will own.
            bucket:read: The application will be able to read the metadata and list contents for OSS buckets that it has access to.
            bucket:update: The application will be able to set permissions and entitlements for OSS buckets that it has permission to modify.
      x-authentication_context: application context required
    3-legged:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://developer.api.autodesk.com/authentication/v2/authorize
          tokenUrl: https://developer.api.autodesk.com/authentication/v2/token
          refreshUrl: https://developer.api.autodesk.com/authentication/v2/token
          scopes:
            data:read: read your data
            data:write: modify your data
            data:create: create new data
      x-authentication_context: user context required
      description: User context required.
    2-legged:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://developer.api.autodesk.com/authentication/v2/token
          scopes:
            data:read: read application accessible data
            data:write: write application accessible data
            data:create: create application accessible data
            bucket:create: create an OSS bucket the application will own
            bucket:read: read the metadata and list contents for OSS buckets the application has access to
            bucket:update: set permissions and entitlements for OSS buckets the application has permission to modify
            bucket:delete: delete an OSS bucket the application owns
            viewables:read: read viewables of application accessible data
      x-authentication_context: application context required
      description: Application context required.
x-provenance:
  method: harvested
  publisher: Autodesk
  source: https://raw.githubusercontent.com/autodesk-platform-services/aps-sdk-openapi/main/oss/oss.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)