> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesa.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Get content
> Get file content or directory listing at a path. Use Accept: application/json for the JSON union response, or Accept: application/octet-stream for raw file bytes. Directory + octet-stream requests return 406 Not Acceptable.
File, symlink, and directory responses include an optional `metadata` field with the path's metadata when any is set; the field is omitted otherwise. Values are plain UTF-8 strings. Directory listings additionally surface per-entry metadata inline on each row in `entries[]` (also UTF-8 strings, omitted when empty). Reads at a historical `change_id` return today's metadata for the resolved path, not the values as of that change (metadata is stored separately from Git history).
Directory listings can be filtered by metadata predicates: `?metadata[key]=value`, repeatable. Multiple keys are AND-ed (exact-value match). Entries without metadata (or with mismatched values) are dropped from `entries[]`. The filter is ignored when the resolved path is a file or symlink.
**Required scope:** `read`
## OpenAPI
````yaml /openapi.json get /{org}/{repo}/content
openapi: 3.1.0
info:
title: Depot API
description: Depot HTTP API v1
version: 1.0.0
servers:
- url: https://api.mesa.dev/v1
security:
- apiKey: []
paths:
/{org}/{repo}/content:
get:
tags:
- Content
summary: Get content
description: >-
Get file content or directory listing at a path. Use Accept:
application/json for the JSON union response, or Accept:
application/octet-stream for raw file bytes. Directory + octet-stream
requests return 406 Not Acceptable.
File, symlink, and directory responses include an optional `metadata`
field with the path's metadata when any is set; the field is omitted
otherwise. Values are plain UTF-8 strings. Directory listings
additionally surface per-entry metadata inline on each row in
`entries[]` (also UTF-8 strings, omitted when empty). Reads at a
historical `change_id` return today's metadata for the resolved path,
not the values as of that change (metadata is stored separately from Git
history).
Directory listings can be filtered by metadata predicates:
`?metadata[key]=value`, repeatable. Multiple keys are AND-ed
(exact-value match). Entries without metadata (or with mismatched
values) are dropped from `entries[]`. The filter is ignored when the
resolved path is a file or symlink.
operationId: getContent
parameters:
- in: path
name: org
schema:
type: string
minLength: 1
required: true
description: Organization slug
- in: path
name: repo
schema:
type: string
minLength: 1
required: true
description: Repository name
- in: query
name: change_id
schema:
type: string
pattern: ^[zyxwvutsrqponmlk]{32}$
description: >-
Change id to read content from. Defaults to the current change at
the default bookmark tip. You may also pass the virtual root change
id (zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz) to read the empty tree.
- in: query
name: path
schema:
type: string
- in: query
name: depth
schema:
type: integer
minimum: 0
maximum: 10
description: >-
Directory traversal depth: 0 for directory metadata only, 1 for
direct children, up to 10
- in: query
name: metadata
schema:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Filter directory `entries[]` to rows whose metadata matches. Pass
one param per key as a deepObject: `?metadata[]=`,
repeatable. Multiple keys are AND-ed (an entry must match every pair
to survive; exact-value match). Ignored when the resolved path is a
file or symlink. Example:
`?metadata[tag]=archived&metadata[lang]=en`.
responses:
'200':
description: Content response
content:
application/json:
schema:
anyOf:
- type: object
properties:
type:
type: string
const: file
name:
type: string
path:
type: string
sha:
type: string
is_conflicted:
type: boolean
size:
type: number
encoding:
type: string
const: base64
content:
type: string
mode:
type: string
enum:
- '100644'
- '100755'
description: POSIX file mode for a regular file
metadata:
description: >-
Metadata attached to this path. Values are UTF-8
strings. Always reflects current values; not
snapshotted with change_id.
type: object
propertyNames:
type: string
additionalProperties:
type: string
required:
- type
- name
- path
- sha
- size
- encoding
- content
- mode
- type: object
properties:
type:
type: string
const: symlink
name:
type: string
path:
type: string
sha:
type: string
is_conflicted:
type: boolean
size:
type: number
encoding:
type: string
const: base64
content:
type: string
mode:
type: string
const: '120000'
description: POSIX file mode for a symlink
metadata:
description: >-
Metadata attached to this path. Values are UTF-8
strings. Always reflects current values; not
snapshotted with change_id.
type: object
propertyNames:
type: string
additionalProperties:
type: string
required:
- type
- name
- path
- sha
- size
- encoding
- content
- mode
- type: object
properties:
type:
type: string
const: dir
name:
type: string
path:
type: string
sha:
type: string
child_count:
type: integer
description: Number of direct children in this directory
entries:
type: array
items:
anyOf:
- type: object
properties:
type:
type: string
const: file
name:
type: string
path:
type: string
sha:
type: string
size:
type: number
mode:
type: string
enum:
- '100644'
- '100755'
description: POSIX file mode for a regular file
metadata:
description: >-
Metadata attached to this entry. Values are
UTF-8 strings. Always reflects current
values; not snapshotted with change_id.
type: object
propertyNames:
type: string
additionalProperties:
type: string
required:
- type
- name
- path
- sha
- size
- mode
- type: object
properties:
type:
type: string
const: symlink
name:
type: string
path:
type: string
sha:
type: string
size:
type: number
mode:
type: string
const: '120000'
description: POSIX file mode for a symlink
metadata:
description: >-
Metadata attached to this entry. Values are
UTF-8 strings. Always reflects current
values; not snapshotted with change_id.
type: object
propertyNames:
type: string
additionalProperties:
type: string
required:
- type
- name
- path
- sha
- size
- mode
- type: object
properties:
type:
type: string
const: dir
name:
type: string
path:
type: string
sha:
type: string
metadata:
description: >-
Metadata attached to this entry. Values are
UTF-8 strings. Always reflects current
values; not snapshotted with change_id.
type: object
propertyNames:
type: string
additionalProperties:
type: string
required:
- type
- name
- path
- sha
metadata:
description: >-
Metadata attached to this directory itself. Values are
UTF-8 strings. Always reflects current values; not
snapshotted with change_id. For per-entry metadata of
children, see `entries[].metadata`.
type: object
propertyNames:
type: string
additionalProperties:
type: string
required:
- type
- name
- path
- sha
- child_count
- entries
application/octet-stream:
schema:
type: string
format: binary
'400':
description: Invalid request
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: object
propertyNames:
type: string
additionalProperties: {}
trace_id:
description: >-
Support correlation id attached to 5xx responses;
quote it when reporting an issue
type: string
required:
- code
- message
required:
- error
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: object
propertyNames:
type: string
additionalProperties: {}
trace_id:
description: >-
Support correlation id attached to 5xx responses;
quote it when reporting an issue
type: string
required:
- code
- message
required:
- error
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: object
propertyNames:
type: string
additionalProperties: {}
trace_id:
description: >-
Support correlation id attached to 5xx responses;
quote it when reporting an issue
type: string
required:
- code
- message
required:
- error
'404':
description: Not found
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: object
propertyNames:
type: string
additionalProperties: {}
trace_id:
description: >-
Support correlation id attached to 5xx responses;
quote it when reporting an issue
type: string
required:
- code
- message
required:
- error
'406':
description: Not acceptable
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: object
propertyNames:
type: string
additionalProperties: {}
trace_id:
description: >-
Support correlation id attached to 5xx responses;
quote it when reporting an issue
type: string
required:
- code
- message
required:
- error
'409':
description: Conflict
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: object
propertyNames:
type: string
additionalProperties: {}
trace_id:
description: >-
Support correlation id attached to 5xx responses;
quote it when reporting an issue
type: string
required:
- code
- message
required:
- error
'500':
description: Internal error
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: object
propertyNames:
type: string
additionalProperties: {}
trace_id:
description: >-
Support correlation id attached to 5xx responses;
quote it when reporting an issue
type: string
required:
- code
- message
required:
- error
components:
securitySchemes:
apiKey:
type: http
scheme: bearer
bearerFormat: API Key
````