Owner

Replace the avatar as an app

Stores the request body as the owner's avatar and returns the profile fields you can read. Requires profile write permission for the avatar.

PUT
/profile/avatar

Authorization

bearerAuth
headerAuthorizationBearer <token>

Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).

Header parameters

X-Marfa-Instance-Id?string

The ID of the instance you expect, as GET / returns it. If another instance answers at this address, Marfa returns 409 instance_changed and doesn't write. Leave it out to send the request to whichever instance answers.

Match^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Request body

The avatar's bytes, sent as they are, not as multipart/form-data. Marfa decides the kind from the bytes and ignores Content-Type and any file name. A PNG, JPEG or WebP of 2 MiB or less, 1 to 4096 pixels on each side.

body*fileapplication/octet-stream
Formatbinary

Response body

About errors

Returns the profile fields you can read. The avatar was stored.

application/json
  1. response

The owner's profile, as far as your credential can read it.

name?string

The owner's name. Present with profile.name:read.

username?string

The owner's username, which password sign-in matches. Present with profile.username:read.

email?|

The owner's email address, or null when none is set. Present with profile.email:read.

Formatemail
avatar?|

The address of the owner's avatar, or null when there is none. Present with profile.avatar:read. Fetch it with GET /profile/avatar.

Formaturi

The body is empty, damaged, not a PNG, JPEG or WebP, or larger than 4096 pixels on a side. For example, a GIF, an AVIF or an SVG.

application/json
  1. response

An error response.

error*

What went wrong.

unauthorized: the request has no credential, or its credential is not valid. For a key that has expired, details.expired_at says when it expired.

application/json
  1. response

An error response.

error*

What went wrong.

The credential lacks profile write permission for the avatar.

application/json
  1. response

An error response.

error*

What went wrong.

The owner is unavailable.

application/json
  1. response

An error response.

error*

What went wrong.

request_timeout: no bytes arrived for 60 seconds. Nothing changed. An upload has no other time limit while bytes keep arriving.

application/json
  1. response

An error response.

error*

What went wrong.

instance_changed: X-Marfa-Instance-Id names another instance. Nothing is written. Rebuild the working copy from the instance at this address.

application/json
  1. response

An error response.

error*

What went wrong.

contract_mismatch: X-Marfa-Contract names another contract version than this instance speaks, or is not a whole number. Nothing was done.

application/json
  1. response

An error response.

error*

What went wrong.

request_too_large: the request body is larger than this instance accepts.

application/json
  1. response

An error response.

error*

What went wrong.

rate_limited: you sent too many requests. Wait for the number of seconds in Retry-After, then try again.

application/json
  1. response

An error response.

error*

What went wrong.

internal_error: Marfa failed in a way it didn't expect, and the request may not have completed. Read what you changed before you repeat a write.

application/json
  1. response

An error response.

error*

What went wrong.

write_contention: the database was busy, and Marfa couldn't complete the request in time. Nothing changed. Try the request again. While a restore runs, details.reason is restore_running.

application/json
  1. response

An error response.

error*

What went wrong.

insufficient_storage: the disk that holds the instance's data has no room for the request, or the request would leave less free than the instance keeps in reserve. Nothing changed, unless details.write_outcome is unknown, which means the write may have landed: read what you changed before you repeat it. Free space on the disk, then try the request again.

application/json
  1. response

An error response.

error*

What went wrong.

curl -X PUT 'http://localhost:8600/profile/avatar' \  -H 'Content-Type: application/octet-stream' \  -d 'string'
About errors
{  "name": "Alex Example",  "username": "alex",  "email": "alex@example.com",  "avatar": "https://marfa.example.com/profile/avatar"}