> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getruba.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Files
> ### Intent
Reads the available files as a pageable collection without changing them.
### When to call it
Call this when an interface, sync, or support workflow needs to inspect files. Use the filters and paging controls shown below to limit the result.
### Access boundary
Authorize the request with a token that carries `files:read` or `files:write`.
### Successful result
A successful request returns `200`. The response schema below defines the body your integration receives.
export const RubaSocials = () => {
if (typeof document === "undefined") {
return null;
}
const inject = () => {
const footer = document.getElementById("footer");
if (!footer || document.getElementById("ruba-socials")) {
return false;
}
const isDark = document.querySelector("html.dark") || document.querySelector('html[class*="dark"]');
const lineColor = isDark ? "#383838" : "#e8e8ed";
const iconColor = isDark ? "#8e8e93" : "#86868b";
const markColor = isDark ? "#ffffff" : "#08080c";
const hoverColor = "#0071e3";
const div = document.createElement("div");
div.id = "ruba-socials";
div.style.cssText = `display:flex;align-items:center;gap:20px;padding-top:20px;margin-top:20px;border-top:1px solid ${lineColor};width:100%`;
const logo = `Ruba`;
const spacer = ``;
const ig = ``;
const li = ``;
const x = ``;
const github = ``;
div.innerHTML = logo + spacer + ig + li + x + github;
footer.appendChild(div);
return true;
};
if (!document.documentElement.dataset.rubaSocialsObserver) {
document.documentElement.dataset.rubaSocialsObserver = "true";
const observer = new MutationObserver(() => {
if (!document.getElementById("ruba-socials")) {
inject();
}
});
observer.observe(document.body, {
childList: true,
subtree: true
});
}
setTimeout(() => {
if (!inject()) {
const interval = setInterval(() => {
if (inject()) {
clearInterval(interval);
}
}, 500);
setTimeout(() => clearInterval(interval), 10000);
}
}, 300);
return null;
};
## OpenAPI
````yaml get /v1/files/
openapi: 3.1.0
info:
title: Ruba API
summary: Ruba HTTP and Webhooks API
description: '**Details:** Read the docs at https://docs.getruba.com/api-reference.'
version: 2026-04
servers:
- url: https://api.getruba.com
description: '**Details:** Production environment.'
x-speakeasy-server-id: production
- url: https://sandbox-api.getruba.com
description: '**Details:** Sandbox environment.'
x-speakeasy-server-id: sandbox
security: []
tags:
- name: public
description: >-
**Details:** Endpoints shown and documented in the Ruba API documentation
and available in our SDKs.
- name: private
description: >-
**Details:** Endpoints that should appear in the schema only in
development to generate our internal JS SDK.
paths:
/v1/files/:
get:
tags:
- files
- public
summary: List Files
description: >-
### Intent
Reads the available files as a pageable collection without changing
them.
### When to call it
Call this when an interface, sync, or support workflow needs to inspect
files. Use the filters and paging controls shown below to limit the
result.
### Access boundary
Authorize the request with a token that carries `files:read` or
`files:write`.
### Successful result
A successful request returns `200`. The response schema below defines
the body your integration receives.
operationId: files:list
parameters:
- name: organization_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid4
description: Identifier of the organization.
examples:
- 1dbfc517-0bbf-4301-9ba8-555ca42b9737
x-ruba-selector-widget:
displayProperty: name
resourceName: Organization
resourceRoot: /v1/organizations
- type: array
items:
type: string
format: uuid4
description: Identifier of the organization.
examples:
- 1dbfc517-0bbf-4301-9ba8-555ca42b9737
x-ruba-selector-widget:
displayProperty: name
resourceName: Organization
resourceRoot: /v1/organizations
- type: 'null'
title: OrganizationID Filter
description: Return only records matching organization ID.
description: Return only records matching organization ID.
- name: ids
in: query
required: false
schema:
anyOf:
- type: string
format: uuid4
- items:
type: string
format: uuid4
type: array
- type: 'null'
title: FileID Filter
description: Return only records matching file ID.
description: Return only records matching file ID.
- name: page
in: query
required: false
schema:
type: integer
exclusiveMinimum: 0
description: Results page to return. The first page is used by default.
default: 1
title: Page
description: Results page to return. The first page is used by default.
- name: limit
in: query
required: false
schema:
type: integer
exclusiveMinimum: 0
description: Records returned per page. Defaults to 10 and accepts up to 100.
default: 10
title: Limit
description: Records returned per page. Defaults to 10 and accepts up to 100.
responses:
'200':
description: Request completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ListResource_FileRead_'
'422':
description: Request validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- oidc:
- files:read
- files:write
- pat:
- files:read
- files:write
- oat:
- files:read
- files:write
components:
schemas:
ListResource_FileRead_:
properties:
items:
items:
oneOf:
- $ref: '#/components/schemas/DownloadableFileRead'
- $ref: '#/components/schemas/ProductMediaFileRead'
- $ref: '#/components/schemas/OrganizationAvatarFileRead'
- $ref: '#/components/schemas/SupportCaseAttachmentFileRead'
title: FileRead
discriminator:
propertyName: service
mapping:
downloadable:
$ref: '#/components/schemas/DownloadableFileRead'
organization_avatar:
$ref: '#/components/schemas/OrganizationAvatarFileRead'
product_media:
$ref: '#/components/schemas/ProductMediaFileRead'
support_case_attachment:
$ref: '#/components/schemas/SupportCaseAttachmentFileRead'
type: array
title: Items
pagination:
$ref: '#/components/schemas/Pagination'
type: object
required:
- items
- pagination
title: ListResource[FileRead]
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
DownloadableFileRead:
properties:
id:
type: string
format: uuid4
title: Id
description: The stable identifier for this record.
organization_id:
type: string
format: uuid4
title: Organization Id
name:
type: string
title: Name
path:
type: string
title: Path
mime_type:
type: string
title: Mime Type
size:
type: integer
title: Size
storage_version:
anyOf:
- type: string
- type: 'null'
title: Storage Version
checksum_etag:
anyOf:
- type: string
- type: 'null'
title: Checksum Etag
checksum_sha256_base64:
anyOf:
- type: string
- type: 'null'
title: Checksum Sha256 Base64
checksum_sha256_hex:
anyOf:
- type: string
- type: 'null'
title: Checksum Sha256 Hex
last_modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Modified At
version:
anyOf:
- type: string
- type: 'null'
title: Version
service:
type: string
const: downloadable
title: Service
is_uploaded:
type: boolean
title: Is Uploaded
created_at:
type: string
format: date-time
title: Created At
size_readable:
type: string
title: Size Readable
readOnly: true
type: object
required:
- id
- organization_id
- name
- path
- mime_type
- size
- storage_version
- checksum_etag
- checksum_sha256_base64
- checksum_sha256_hex
- last_modified_at
- version
- service
- is_uploaded
- created_at
- size_readable
title: DownloadableFileRead
description: File to be associated with the downloadables benefit.
ProductMediaFileRead:
properties:
id:
type: string
format: uuid4
title: Id
description: The stable identifier for this record.
organization_id:
type: string
format: uuid4
title: Organization Id
name:
type: string
title: Name
path:
type: string
title: Path
mime_type:
type: string
title: Mime Type
size:
type: integer
title: Size
storage_version:
anyOf:
- type: string
- type: 'null'
title: Storage Version
checksum_etag:
anyOf:
- type: string
- type: 'null'
title: Checksum Etag
checksum_sha256_base64:
anyOf:
- type: string
- type: 'null'
title: Checksum Sha256 Base64
checksum_sha256_hex:
anyOf:
- type: string
- type: 'null'
title: Checksum Sha256 Hex
last_modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Modified At
version:
anyOf:
- type: string
- type: 'null'
title: Version
service:
type: string
const: product_media
title: Service
is_uploaded:
type: boolean
title: Is Uploaded
created_at:
type: string
format: date-time
title: Created At
size_readable:
type: string
title: Size Readable
readOnly: true
public_url:
type: string
title: Public Url
readOnly: true
type: object
required:
- id
- organization_id
- name
- path
- mime_type
- size
- storage_version
- checksum_etag
- checksum_sha256_base64
- checksum_sha256_hex
- last_modified_at
- version
- service
- is_uploaded
- created_at
- size_readable
- public_url
title: ProductMediaFileRead
description: File to be used as a product media file.
OrganizationAvatarFileRead:
properties:
id:
type: string
format: uuid4
title: Id
description: The stable identifier for this record.
organization_id:
type: string
format: uuid4
title: Organization Id
name:
type: string
title: Name
path:
type: string
title: Path
mime_type:
type: string
title: Mime Type
size:
type: integer
title: Size
storage_version:
anyOf:
- type: string
- type: 'null'
title: Storage Version
checksum_etag:
anyOf:
- type: string
- type: 'null'
title: Checksum Etag
checksum_sha256_base64:
anyOf:
- type: string
- type: 'null'
title: Checksum Sha256 Base64
checksum_sha256_hex:
anyOf:
- type: string
- type: 'null'
title: Checksum Sha256 Hex
last_modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Modified At
version:
anyOf:
- type: string
- type: 'null'
title: Version
service:
type: string
const: organization_avatar
title: Service
is_uploaded:
type: boolean
title: Is Uploaded
created_at:
type: string
format: date-time
title: Created At
size_readable:
type: string
title: Size Readable
readOnly: true
public_url:
type: string
title: Public Url
readOnly: true
type: object
required:
- id
- organization_id
- name
- path
- mime_type
- size
- storage_version
- checksum_etag
- checksum_sha256_base64
- checksum_sha256_hex
- last_modified_at
- version
- service
- is_uploaded
- created_at
- size_readable
- public_url
title: OrganizationAvatarFileRead
description: File to be used as an organization avatar.
SupportCaseAttachmentFileRead:
properties:
id:
type: string
format: uuid4
title: Id
description: The stable identifier for this record.
organization_id:
type: string
format: uuid4
title: Organization Id
name:
type: string
title: Name
path:
type: string
title: Path
mime_type:
type: string
title: Mime Type
size:
type: integer
title: Size
storage_version:
anyOf:
- type: string
- type: 'null'
title: Storage Version
checksum_etag:
anyOf:
- type: string
- type: 'null'
title: Checksum Etag
checksum_sha256_base64:
anyOf:
- type: string
- type: 'null'
title: Checksum Sha256 Base64
checksum_sha256_hex:
anyOf:
- type: string
- type: 'null'
title: Checksum Sha256 Hex
last_modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Modified At
version:
anyOf:
- type: string
- type: 'null'
title: Version
service:
type: string
const: support_case_attachment
title: Service
is_uploaded:
type: boolean
title: Is Uploaded
created_at:
type: string
format: date-time
title: Created At
size_readable:
type: string
title: Size Readable
readOnly: true
type: object
required:
- id
- organization_id
- name
- path
- mime_type
- size
- storage_version
- checksum_etag
- checksum_sha256_base64
- checksum_sha256_hex
- last_modified_at
- version
- service
- is_uploaded
- created_at
- size_readable
title: SupportCaseAttachmentFileRead
description: File attached to a support case (private; fetched via presigned URL).
Pagination:
properties:
total_count:
type: integer
title: Total Count
max_page:
type: integer
title: Max Page
type: object
required:
- total_count
- max_page
title: Pagination
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:
oidc:
type: openIdConnect
openIdConnectUrl: /.well-known/openid-configuration
pat:
type: http
description: >-
**Authentication:** You can generate a **Personal Access Token** from
your [settings](https://getruba.com/settings).
scheme: bearer
oat:
type: http
description: >-
**Authentication:** You can generate an **Organization Access Token**
from your organization's settings.
scheme: bearer
````