# Upload app assets

Upload an image through the Orbit REST API, then use its public content address when you add it to your app.

This guide is for developers who use the API. An upload stores the file; it does not place an image on a page.

## Before you start

You need curl, an Orbit API token, your app identifier, and a local image file. Use a token for the organization that owns the app.

Keep your token out of screenshots, shared files, and app content. The [Orbit REST API reference](https://api.orbitapps.io/swagger) describes authentication and the artifact endpoints.

## Upload and use a public image

Use `public` only for files that anyone can read. Do not upload private client data as a public asset.

1. Set these shell variables to your own values:

   ```sh
   export ORBIT_TOKEN='your-token'
   export ORBIT_APP_ID='your-app-uuid'
   ```

2. In the upload command below, replace `./logo.png` with your local image path.
3. Run the upload command:

   ```sh
   curl --include --fail-with-body \
     -X POST 'https://api.orbitapps.io/api/v1/artifacts' \
     -H "Authorization: Bearer $ORBIT_TOKEN" \
     -F 'file=@./logo.png' \
     -F "app=$ORBIT_APP_ID" \
     -F 'visibility=public'
   ```

   Do not set a JSON content type: this request sends multipart form data.

4. Check that the response status is HTTP `201`. Keep the returned `id` and `content_url`.
5. Ask Orbit Agent to use the returned `content_url` on the intended page. For example:

   > Use this public image address as the logo in the header of the home page. Keep the rest of the page unchanged.

   Add your actual public address to that request. Follow [Add a page](/guides/add-a-page) for the Orbit Agent input controls.

Use `content_url` for an image that a deployed page must display. Private artifacts have no public content address. If you omit `visibility`, Orbit stores the file as private.

Upload success does not mean that the app displays the file. [Edit a mockup](/guides/edit-a-mockup) to inspect the page after Orbit Agent places the image.

## If the upload fails

- HTTP `400` with `artifact-file-missing`: send a multipart field named `file`.
- HTTP `413`: upload a smaller file.
- HTTP `422` with `artifact-bad-app-id`: check that `app` contains the app's UUID.
- HTTP `403` with `org-scope-required`: use an organization-scoped token, or provide `X-Orbit-Org` for an organization where you are an active member.