# Get an image

> The media.get operation: GET /api/v1/media/{fileId} in the REST API and the media_get tool in the MCP server.

Returns an uploaded image's type, size, SHA-256 and path: an organization's or legal entity's image, a brand's
logo or icon, or a person's photo. The console loads images from their path (`/media/{fileId}/{sha256}.{ext}`),
which runs this check first.

**Who can see what:** organization, entity and brand images, the organization's members (any role); a person's
photo, the person and the members of organizations they belong to; Ownrecord staff, every image. Anything else
is `resource_not_found`, exactly like an image that doesn't exist. Brand logos and icons are also public once the
brand is in test or live mode (`media.public.get`). API keys can't call it.

## At a glance

- **REST:** `GET /api/v1/media/{fileId}`
- **MCP tool:** `media_get`
- **Operation ID:** `media.get`
- **Scope:** Platform
- **Permission:** `account:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Authentication:** API key with the `account:read` scope
- **Since:** M13

## Request

### Path parameters

| Field    | Type        | Description                                              |
| -------- | ----------- | -------------------------------------------------------- |
| `fileId` | `file_…` ID | The image's file ID (`file_…`), as in its `/media` path. |

### Query parameters

This operation takes no query parameters.

## Response

`200 OK` with a JSON object:

| Field         | Type                                                                            | Description                                                                           |
| ------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `id`          | `file_…` ID                                                                     |                                                                                       |
| `object`      | `"media"`                                                                       |                                                                                       |
| `kind`        | one of `org_avatar`, `entity_avatar`, `brand_logo`, `brand_icon`, `user_avatar` |                                                                                       |
| `contentType` | one of `image/png`, `image/jpeg`, `image/webp`                                  |                                                                                       |
| `size`        | integer (at least 0)                                                            |                                                                                       |
| `sha256`      | string                                                                          | Hex SHA-256 of the bytes; the route checks it.                                        |
| `url`         | string                                                                          | `/media/{fileId}/{sha256}.{ext}`, relative to the app's URL.                          |
| `visibility`  | one of `public`, `private`                                                      | `public`: anyone may load it (brand logos and icons); `private`: only who may see it. |

## Examples

### The organization's image

```http
GET /api/v1/media/file_01m4tx5nj8emwbyf7y9vcf47yc
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "id": "file_01m4tx5nj8emwbyf7y9vcf47yc",
  "object": "media",
  "kind": "org_avatar",
  "contentType": "image/png",
  "size": 68,
  "sha256": "63ef318d96b5d0d0ceba6e04a4e622b1158335cdc67c49e27839132c6f655058",
  "url": "/media/file_01m4tx5nj8emwbyf7y9vcf47yc/63ef318d96b5d0d0ceba6e04a4e622b1158335cdc67c49e27839132c6f655058.png",
  "visibility": "private"
}
```

## Errors

| Code                                                                                     | HTTP status | When                                                                    | What to do                                                                                           |
| ---------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed)   | 400         | `fileId` isn't a file ID.                                               | Fix the fields listed in `details.issues` and send the request again.                                |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404         | There is no such image, or you may not see it (the answer is the same). | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)   | 403         | The caller isn't a signed-in user (for example, an API key).            | Ask an organization owner or admin for a role or scope that allows this action.                      |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).