For AI agents: this page is also available as Markdown at https://docs.refabric.com/api-reference/platform/files/read-a-file.md, and the index of every page is https://docs.refabric.com/llms.txt.
Platform API › Files
Read a file
One file or record by its address, with its URL and what it holds.
https://api.refabric.com/v1/files/{ref}import os
import requests
url = "https://api.refabric.com/v1/files/{ref}"
headers = {"Authorization": f"Key {os.environ['REFABRIC_API_KEY']}"}
response = requests.get(url, headers=headers)
print(response.json()){
"url": "https://files.refabric.com/art/3f2a.png",
"media_type": "image/png",
"file": "art:3f2a",
"task": "image.expand",
"job_id": "9b2f4c1d0e8a",
"created_at": "2026-10-05T09:30:12Z",
"data": {}
}Modes
- 1. Full (
view=full, the default) — everything the file or record holds. - 2. Basic (
view=basic) — its summary.
Authentication. A key with files:read: the files are your account's.
Common use cases
- Read a record a job made, or check an upload before you use it.
See also
POST /v1/filesGET /v1/refs/{kind}
Authorization
Authorization: Key $REFABRIC_API_KEYScope: files:read
Parameters
Path parameters
- stringrequired
Query parameters
- stringoptionalDefault:
fullHow much of it to answer.
pattern: ^(basic|full)$
Values
full— Everything the file or record says.basic— Its summary: a record without its parts.
Header parameters
- stringoptional
The contract version you wrote against (a date). Absent: the current version.
format: date
- stringoptional
Your own id for this request; we answer it back under X-Client-Request-ID.
max length 128
Response
200 — Done: the answer is in the body.
- stringrequired
Where the file is. A public, permanent address you can open or download.
Example:
https://files.refabric.com/art/3f2a.png - stringrequired
The file's standard media type.
Example:
image/png - stringrequired
Its address; pass it to a task as it is.
Example:
art:3f2a - stringoptionalnullable
The task that made it.
Example:
image.expand - stringoptionalnullable
The job that made it.
Example:
9b2f4c1d0e8a - stringoptionalnullable
When it was made, ISO-8601 in UTC.
Example:
2026-10-05T09:30:12Z - objectoptionalnullable
What the file means, in the record vocabulary.
- stringoptionalnullable
The record's name.
Example:
SS27 - stringoptionalnullable
What the record is, in words.
Example:
A calm palette. - stringoptionalnullable
Whether it can be used yet.
Values
processing— Still being made or analysed. Read it again later.ready— Finished. It can be passed to a task.failed— It could not be made. Its content is missing.
Example:
ready - array<object>optionalnullable
Its colours.
Example:
[{"hex":"#1f2a44"}]- stringrequired
The colour as
#rrggbb.Example:
#1f2a44 - stringoptionalnullable
Its name, when known.
Example:
Navy - stringoptionalnullable
The nearest Pantone code, when known.
Example:
19-4024 TCX
- array<object>optionalnullable
Its parts (a pose preset: its poses and views).
Example:
[{"type":"fabric"}]ItemEntry
- stringrequired
What the part is.
Values
fabric— A fabric: its swatch or a photo of it. When the image is a fabric swatch or a photo of a fabric.print— A print or pattern. When the image is a print or pattern.look— A garment or outfit, as a photo or a design. When the image is a garment or an outfit.detail— A close crop of one detail of a look or a product (a collar, a pocket). When the image is a close crop of one detail.design— One cell of a range plan: a design made for one garment line.other— Any other image the record holds. When the image is none of the other kinds.product— A photo of the product itself, as supplied (view: which side). When the photo is the product itself;viewsays which side.label— A photo of the product's label (care, size or brand label). When the photo is of the product's label.ghost— The product on an invisible (ghost) mannequin (view: which side). When you want the product shown on an invisible mannequin.flat— The product laid flat, as a flat-lay photo (view: which side). When you want the product laid flat.close_up— A close-up of the product's fabric and finish (one per product in a shoot). Notdetail, which is a crop of one trim or component of a look. When you want a close-up of the product's fabric and finish.
Example:
fabric - stringoptionalnullable
Which side it shows.
Example:
front - stringoptionalnullable
Its name.
Example:
Wool twill - stringoptionalnullable
Your own id for it, when you sent one.
Example:
SKU-1 - stringoptionalnullable
What it is, in words.
Example:
A navy wool twill. - stringoptionalnullable
Its image — pass it to a task as it is.
Example:
https://files.refabric.com/art/3f2a.png - stringoptionalnullable
Whether it can be used yet.
Values
processing— Still being made or analysed. Read it again later.ready— Finished. It can be passed to a task.failed— It could not be made. Its content is missing.
Example:
ready
PresetItem
- stringrequired
How the entry names what it wants: a saved pose, an image, words, or a product view.
Example:
view - stringrequired
The pose's address (
pose:…); empty for a view.Example:
pose:812 - stringrequirednullable
The pose's camera angle.
Example:
front - stringrequirednullable
The product view it shows.
Example:
back
- array<string>optionalnullable
Words that sum it up.
Example:
["tailoring"]
- 400 — The request cannot be read as it was sent (a header, the URL or the body's form).
- 401 — No valid API key was sent.
- 403 — Your key or your plan does not allow this.
- 404 — Nothing has this address.
- 422 — A field is missing or has a value this operation cannot use.
- 429 — Too many requests: wait for the number of seconds in the Retry-After header.
- 500 — Something went wrong on our side; retry, and quote the request id if it keeps happening.