Skip to content
calternal docs

Find a Files item by ID

GET
/api/v1/files/items/{id}
curl --request GET \
  --url https://example.com/api/v1/files/items/example \
  --header 'Authorization: Bearer <token>'

Requires a signed-in User with the data scope and read access to the Item. It returns 404 when the ID is invalid, missing or not shared with the User. Route: /api/v1/files/items/{id}. Inputs: id. Safe reads can use bounded retries.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
entry
required
object
canvas_note_id

Indexed Canvas identity, including plain JSON without frontmatter (#991). Set only after this listing’s current Files grant has passed.

string | null
changed_by

Named guest who created this previous Version through a public Edit link, when there is one.

string | null
content_hash
string | null
created

Inode creation time, when the Home filesystem reports statx birth time.

string | null
has_thumbnail
required
boolean
item_id
string | null
kind
required
string
mime
string | null
modified
required
string
name
required
string
original_path

Trash listings only: the Home-relative path the item is restored to.

string | null
share_badges
required
Array<string>
size
required
integer format: int64
path
required

The path the viewer passes to other Files routes: Home-relative for the owner, Shared/<owner>/<path> for a Share recipient.

string
Examplegenerated
{
  "entry": {
    "canvas_note_id": "example",
    "changed_by": "example",
    "content_hash": "example",
    "created": "example",
    "has_thumbnail": true,
    "item_id": "example",
    "kind": "example",
    "mime": "example",
    "modified": "example",
    "name": "example",
    "original_path": "example",
    "share_badges": [
      "example"
    ],
    "size": 1
  },
  "path": "example"
}

404

Section titled “404”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}