canonical: https://jentic.com/apis/appwrite.io/client

# Appwrite

Jentic publishes the only available OpenAPI specification for Appwrite, keeping it validated and agent-ready. This is the client-side surface of the Appwrite open-source backend-as-a-service - 61 operations across 41 paths covering end-user account flows, OAuth2 sessions, anonymous sessions, JWT tokens, document reads and writes, file storage, team membership, and avatar generation. It is intended for code that runs in the user's browser or device, where calls are authenticated by the user's session, not an admin key.

## For AI agents

Client-side Appwrite surface for end-user flows: account, sessions, OAuth, JWTs, documents, files, teams, avatars. 61 endpoints authenticated by user session.

## Scope

Does not expose admin operations such as creating users without sign-up or writing as another user - use the Appwrite Server API for those; this client API is session-scoped only.

## Capabilities

- Sign up, log in, and manage sessions including OAuth2 providers and anonymous sessions via /account/sessions
- Issue and verify JWTs for the current user via /account/jwt
- Read and write documents subject to per-collection user permissions
- Upload and download files in buckets where the user has read/write rights
- Join, leave, and read teams the current user belongs to via /teams memberships
- Generate avatars, country flags, and credit-card art for UI rendering
- Send and verify email recovery and account verification flows

## Use cases

### Mobile/SPA Authentication

A single-page web app or mobile client uses the Appwrite client API for end-user auth - POST /account/sessions for email login, POST /account/sessions/oauth2/{provider} for Google or GitHub login, POST /account/sessions/anonymous for guest access, and POST /account/jwt to mint short-lived JWTs that downstream services can verify. The session cookie carries the authenticated user identity for subsequent calls.

Example prompt: POST /account/sessions/oauth2/google with success and failure redirects, then on return call POST /account/jwt to issue a JWT

### User-Owned Document Workspace

A note-taking or productivity app stores per-user documents in Appwrite collections with row-level read/write rules tied to the user id. The client surface lets the user list, create, update, and delete only the documents they own, while shared documents become accessible via team membership rules. No server-side admin key is required client-side.

Example prompt: POST /database/collections/{collectionId}/documents with permissions ['user:CURRENT_USER_ID'] and the note body

### Direct File Upload from Browser

A file-sharing UI lets users upload directly from the browser to Appwrite storage, bypassing the application server. POST /storage/files accepts the file with a session cookie and bucket-level permissions; downloads stream from GET /storage/files/{fileId}/download. This pattern reduces backend bandwidth costs and shortens upload time for large files.

Example prompt: POST /storage/files with a file object and the user's session cookie, then call GET /storage/files/{fileId}/preview for a thumbnail

### AI Agent Acting On Behalf Of A User

An AI agent that has been delegated user credentials uses Jentic to operate on the user's Appwrite data - reading their documents, uploading files, joining teams. Because this is the client surface, the agent works with a session JWT scoped to one user, not an admin key, which keeps the blast radius contained.

Example prompt: Search Jentic for 'list user's documents in appwrite', call GET /database/collections/{collectionId}/documents with the user's session JWT, and return documents the user owns

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /account | Create a new user account |
| POST | /account/sessions | Create a new session by email and password |
| POST | /account/jwt | Issue a JWT for the current user |
| GET | /account/sessions/oauth2/{provider} | Start an OAuth2 flow with a provider |
| POST | /storage/files | Upload a file to a storage bucket |
| GET | /avatars/initials | Generate an avatar from a user's initials |

## Key resources

- **account** — Authenticated user profile, sessions, prefs, and recovery
- **account/sessions** — Email, OAuth2, anonymous, and magic-link sessions
- **account/jwt** — Issue JWTs for the currently logged-in user
- **database** — Read and write documents the user has access to
- **storage** — Upload and download files in user-permitted buckets
- **teams** — Read and manage team memberships for the current user
- **avatars** — Generate avatars, flags, and decorative images for UI

## Why Jentic

- **Setup:** Wiring the Appwrite client surface by hand means managing the X-Appwrite-Project header plus a per-user JWT or session cookie, and following the account and session flows yourself. Through Jentic you install once, import the Appwrite Client API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** The client surface scopes the JWT to the requesting user and takes its targets in the request body, so you limit the agent to the operations it needs, such as signing in a user or uploading a file as that user. You choose the operations it may call, and the agent operates within that single user's permissions rather than holding an admin key.
- **Credential handling:** Your Appwrite project header and per-user JWT or session cookie are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'sign in a user with Google' or 'upload a file as a user', and Jentic returns the matching client-surface Appwrite operation with its parameters and response schema so the agent calls the right endpoint without navigating the docs site.

## Related APIs

- **Appwrite Server API** — Admin-key surface that complements the user-session client surface
- **Supabase API** — Postgres-backed open-source backend with a similar client/server split
- **Firebase API** — Google's BaaS with a similar client SDK pattern for auth, database, and storage

## FAQ

### Why is there no official OpenAPI spec for Appwrite?

Appwrite does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Appwrite via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Appwrite Client API use?

It uses two headers: Project (the Appwrite project id) and JWT (a short-lived JWT minted via POST /account/jwt or a session cookie set after /account/sessions). Server-side admin keys are NOT valid here - this surface is for end-user contexts only. Through Jentic the project id and JWT are vaulted and attached at execution.

### Can I sign in with Google or GitHub through the Client API?

Yes. POST /account/sessions/oauth2/{provider} starts an OAuth2 redirect with the chosen provider (google, github, facebook, apple, and others supported by Appwrite). After the user returns, the session is established and you can call POST /account/jwt to mint a JWT for downstream calls.

### What are the rate limits for the Appwrite Client API?

Self-hosted Appwrite has no enforced rate limit beyond your server's capacity. Appwrite Cloud applies plan-based quotas covering bandwidth, storage, function executions, and database operations. Sessions endpoints carry tighter per-IP brute-force protection regardless of plan.

### How do I issue a JWT for the current user through Jentic?

Run pip install jentic, search 'issue appwrite jwt', load POST /account/jwt, and execute it with the active session cookie or token. Jentic returns the signed JWT, which the agent can pass to downstream services that verify Appwrite-issued tokens.

### Is the Appwrite Client API free?

Self-hosted Appwrite is open source under BSD-3-Clause and free. Appwrite Cloud has a free tier for hobby projects plus paid Pro and Scale tiers; the same client API is available on every plan.

### Can I limit what my agent is allowed to do with the Appwrite Client API?

Yes. Jentic One is self-hosted by you, so your own rules decide which client operations the agent may call and which credentials it may use. Because this is the client surface, the JWT is scoped to a single requesting user rather than an admin key, so you can restrict the agent to just the operations it needs, such as signing in a user with POST /account/sessions or uploading a file with POST /storage/files. The agent then acts only within that one user's permissions, and any operation you do not grant stays off limits.