SpyBara
Go Premium

cli/resources/files/index.md 2026-07-07 08:02 UTC to 2026-07-09 20:58 UTC

493 added, 0 removed.

2026
Thu 9 20:58 Tue 7 08:02

Files

List files

$ openai files list

get /files

List files

Parameters

  • --after: optional string

    A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.

  • --limit: optional number

    A limit on the number of objects to be returned. Limit can range between 1 and 10,000, and the default is 10,000.

  • --order: optional "asc" or "desc"

    Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.

  • --purpose: optional string

    Only return files with the given purpose.

Returns

  • ListFilesResponse: object { data, first_id, has_more, 2 more }

    • data: array of FileObject

      • id: string

        The file identifier, which can be referenced in the API endpoints.

      • bytes: number

        The size of the file, in bytes.

      • created_at: number

        The Unix timestamp (in seconds) for when the file was created.

      • filename: string

        The name of the file.

      • object: "file"

        The object type, which is always file.

      • purpose: "assistants" or "assistants_output" or "batch" or 5 more

        The intended purpose of the file. Supported values are assistants, assistants_output, batch, batch_output, fine-tune, fine-tune-results, vision, and user_data.

        • "assistants"

        • "assistants_output"

        • "batch"

        • "batch_output"

        • "fine-tune"

        • "fine-tune-results"

        • "vision"

        • "user_data"

      • status: "uploaded" or "processed" or "error"

        Deprecated. The current status of the file, which can be either uploaded, processed, or error.

        • "uploaded"

        • "processed"

        • "error"

      • expires_at: optional number

        The Unix timestamp (in seconds) for when the file will expire.

      • status_details: optional string

        Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

    • first_id: string

    • has_more: boolean

    • last_id: string

    • object: string

Example

openai files list \
  --api-key 'My API Key'

Response

{
  "data": [
    {
      "id": "id",
      "bytes": 0,
      "created_at": 0,
      "filename": "filename",
      "object": "file",
      "purpose": "assistants",
      "status": "uploaded",
      "expires_at": 0,
      "status_details": "status_details"
    }
  ],
  "first_id": "file-abc123",
  "has_more": false,
  "last_id": "file-abc456",
  "object": "list"
}

Upload file

$ openai files create

post /files

Upload file

Parameters

  • --file: string

    The File object (not file name) to be uploaded.

  • --purpose: unknown

  • --expires-after: optional object { anchor, seconds }

    The expiration policy for a file. By default, files with purpose=batch expire after 30 days and all other files are persisted until they are manually deleted.

Returns

  • file_object: object { id, bytes, created_at, 6 more }

    The File object represents a document that has been uploaded to OpenAI.

    • id: string

      The file identifier, which can be referenced in the API endpoints.

    • bytes: number

      The size of the file, in bytes.

    • created_at: number

      The Unix timestamp (in seconds) for when the file was created.

    • filename: string

      The name of the file.

    • object: "file"

      The object type, which is always file.

    • purpose: "assistants" or "assistants_output" or "batch" or 5 more

      The intended purpose of the file. Supported values are assistants, assistants_output, batch, batch_output, fine-tune, fine-tune-results, vision, and user_data.

      • "assistants"

      • "assistants_output"

      • "batch"

      • "batch_output"

      • "fine-tune"

      • "fine-tune-results"

      • "vision"

      • "user_data"

    • status: "uploaded" or "processed" or "error"

      Deprecated. The current status of the file, which can be either uploaded, processed, or error.

      • "uploaded"

      • "processed"

      • "error"

    • expires_at: optional number

      The Unix timestamp (in seconds) for when the file will expire.

    • status_details: optional string

      Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Example

openai files create \
  --api-key 'My API Key' \
  --file 'Example data' \
  --purpose '{}'

Response

{
  "id": "id",
  "bytes": 0,
  "created_at": 0,
  "filename": "filename",
  "object": "file",
  "purpose": "assistants",
  "status": "uploaded",
  "expires_at": 0,
  "status_details": "status_details"
}

Delete file

$ openai files delete

delete /files/{file_id}

Delete file

Parameters

  • --file-id: string

    The ID of the file to use for this request.

Returns

  • file_deleted: object { id, deleted, object }

    • id: string

    • deleted: boolean

    • object: "file"

Example

openai files delete \
  --api-key 'My API Key' \
  --file-id file_id

Response

{
  "id": "id",
  "deleted": true,
  "object": "file"
}

Retrieve file

$ openai files retrieve

get /files/{file_id}

Retrieve file

Parameters

  • --file-id: string

    The ID of the file to use for this request.

Returns

  • file_object: object { id, bytes, created_at, 6 more }

    The File object represents a document that has been uploaded to OpenAI.

    • id: string

      The file identifier, which can be referenced in the API endpoints.

    • bytes: number

      The size of the file, in bytes.

    • created_at: number

      The Unix timestamp (in seconds) for when the file was created.

    • filename: string

      The name of the file.

    • object: "file"

      The object type, which is always file.

    • purpose: "assistants" or "assistants_output" or "batch" or 5 more

      The intended purpose of the file. Supported values are assistants, assistants_output, batch, batch_output, fine-tune, fine-tune-results, vision, and user_data.

      • "assistants"

      • "assistants_output"

      • "batch"

      • "batch_output"

      • "fine-tune"

      • "fine-tune-results"

      • "vision"

      • "user_data"

    • status: "uploaded" or "processed" or "error"

      Deprecated. The current status of the file, which can be either uploaded, processed, or error.

      • "uploaded"

      • "processed"

      • "error"

    • expires_at: optional number

      The Unix timestamp (in seconds) for when the file will expire.

    • status_details: optional string

      Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Example

openai files retrieve \
  --api-key 'My API Key' \
  --file-id file_id

Response

{
  "id": "id",
  "bytes": 0,
  "created_at": 0,
  "filename": "filename",
  "object": "file",
  "purpose": "assistants",
  "status": "uploaded",
  "expires_at": 0,
  "status_details": "status_details"
}

Retrieve file content

$ openai files content

get /files/{file_id}/content

Retrieve file content

Parameters

  • --file-id: string

    The ID of the file to use for this request.

Returns

  • unnamed_schema_0: file path

Example

openai files content \
  --api-key 'My API Key' \
  --file-id file_id

Domain Types

File Content

  • file_content: string

File Deleted

  • file_deleted: object { id, deleted, object }

    • id: string

    • deleted: boolean

    • object: "file"

File Object

  • file_object: object { id, bytes, created_at, 6 more }

    The File object represents a document that has been uploaded to OpenAI.

    • id: string

      The file identifier, which can be referenced in the API endpoints.

    • bytes: number

      The size of the file, in bytes.

    • created_at: number

      The Unix timestamp (in seconds) for when the file was created.

    • filename: string

      The name of the file.

    • object: "file"

      The object type, which is always file.

    • purpose: "assistants" or "assistants_output" or "batch" or 5 more

      The intended purpose of the file. Supported values are assistants, assistants_output, batch, batch_output, fine-tune, fine-tune-results, vision, and user_data.

      • "assistants"

      • "assistants_output"

      • "batch"

      • "batch_output"

      • "fine-tune"

      • "fine-tune-results"

      • "vision"

      • "user_data"

    • status: "uploaded" or "processed" or "error"

      Deprecated. The current status of the file, which can be either uploaded, processed, or error.

      • "uploaded"

      • "processed"

      • "error"

    • expires_at: optional number

      The Unix timestamp (in seconds) for when the file will expire.

    • status_details: optional string

      Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

File Purpose

  • file_purpose: unknown