# Tevello API – Public Machine-Readable Docs

This Markdown file mirrors the Tevello public API documentation available at the HTML `https://api.tevello.com` page. It is intended for AI agents, scripts, and tooling to consume as plain text.

> Public URLs:
> - HTML docs: `https://api.tevello.com`
> - Markdown: `https://api.tevello.com/docs.md`
> - OpenAPI: `https://api.tevello.com/openapi.json`

## Authentication

All Tevello **API endpoints** (under `/{shop}/...`) require a shop-specific Bearer token:

```http
Authorization: Bearer <token>
```

The documentation **HTML page** at `https://api.tevello.com` is gated by a shared password (or by sending `Authorization: Bearer <password>` on the HTML request). This `docs.md` file itself is public.

## Member Management

### GET `/{shop}/member/{member}`

Retrieves detailed information about a specific member, including profile fields, enrolled courses, and communities.

### POST `/{shop}/member/{member}/progress`

Updates a member's progress in a course.

Request body:

```json
{
  "course_id": "COURSE_ID",
  "progress": ["LESSON_ID", "LESSON_ID", "LESSON_ID"]
}
```

### POST `/{shop}/member/{member}/enrollments`

Creates or updates a course or community enrollment for the member.

- Send **either** `course_id` **or** `community_id` (exactly one).
- `expire_at`:
  - Optional.
  - Defaults to `never` (unlimited access).
  - Use a past ISO 8601 datetime to revoke/void access.
- `created_at`:
  - Optional.
  - Defaults to current time when omitted.
  - Must be an ISO 8601 datetime when provided.

Example:

```json
{
  "course_id": "COURSE_ID",
  "created_at": "2026-01-01T00:00:00.000Z"
}
```

## Courses

### GET `/{shop}/courses`

Retrieves all courses available for the shop.

### PUT `/{shop}/courses`

Replaces all courses for the shop.

Request body:

```json
[
  { "id": "COURSE_ID_1", "title": "Course one", "modules": [] },
  { "id": "COURSE_ID_2", "title": "Course two", "modules": [ /* ... */ ] }
]
```

### GET `/{shop}/courses/{course}`

Retrieves a single course by id.

### PUT `/{shop}/courses/{course}`

Creates or updates a course.

Request body (shape, not exhaustive):

```json
{
  "id": "COURSE_ID",
  "title": "Course title",
  "modules": [
    {
      "id": "MODULE_ID",
      "title": "Module title",
      "lessons": [
        { "id": "LESSON_ID", "title": "Lesson title" }
      ]
    }
  ]
}
```

## Settings

### GET `/{shop}/settings`

Retrieves the shop's Tevello settings.

### PUT `/{shop}/settings`

Updates the shop's settings.

Example body (shape only):

```json
{
  "customCSS": "...",
  "translate": { /* ... */ }
}
```

## Communities

### GET `/{shop}/communities`

Retrieves all communities for the shop.

### PUT `/{shop}/communities`

Replaces all communities.

```json
[
  { "id": "COMMUNITY_ID_1", "title": "Community one" },
  { "id": "COMMUNITY_ID_2", "title": "Community two" }
]
```

### GET `/{shop}/communities/{community}`

Retrieves a single community by id.

### PUT `/{shop}/communities/{community}`

Creates or updates a community.

```json
{
  "id": "COMMUNITY_ID",
  "title": "Community title",
  "visibility": "open"
}
```

## Community Posts

### GET `/{shop}/communities/{community}/posts`

Retrieves posts for a specific community.

Query parameters:

- `page` (optional): page number (default: `1`).
- `sort` (optional): `newest-posts` or `newest-activity` (default: `newest-posts`).

### POST `/{shop}/communities/{community}/posts`

Creates a new post.

```json
{
  "content": "HTML Content",
  "topic": "TOPIC",
  "author": "MEMBER_ID"
}
```

### POST `/{shop}/communities/{community}/posts/{post}`

Updates a post.

```json
{
  "content": "HTML Content",
  "topic": "TOPIC"
}
```

### DELETE `/{shop}/communities/{community}/posts/{post}`

Deletes a post.

## Community Comments

### GET `/{shop}/communities/{community}/posts/{post}/comments`

Retrieves comments for a specific post.

### POST `/{shop}/communities/{community}/posts/{post}/comments`

Creates a new comment.

```json
{
  "content": "HTML Content",
  "author": "MEMBER_ID"
}
```

### POST `/{shop}/communities/{community}/posts/{post}/comments/{comment}`

Updates a comment.

```json
{
  "content": "HTML Content"
}
```

### DELETE `/{shop}/communities/{community}/posts/{post}/comments/{comment}`

Deletes a comment.

## Member Posts

### GET `/{shop}/member/{member}/posts`

Retrieves all posts created by a specific member.

## Community Reactions

### GET `/{shop}/communities/reactions`

Retrieves all reactions for a specific post or comment.

Query parameters:

- `parent_id` (required): ID of the post or comment.

### POST `/{shop}/communities/reactions`

Toggles a reaction by a member.

```json
{
  "parent_id": "PARENT_ID",
  "reaction": "REACTION",
  "author": "MEMBER_ID"
}
```

## Uploads

### POST `/{shop}/upload/url`

Returns a presigned PUT URL for uploading a file (image, PDF, etc.).

Request:

```json
{
  "filename": "document.pdf"
}
```

Response (shape):

```json
{
  "put_url": "https://...",
  "content_url": "https://cdn.tevello.com/{shop}/{uuid}.{ext}",
  "expires_in": 3600
}
```

### POST `/{shop}/upload/video/url`

Returns TUS upload parameters for video. Upload the file via TUS to `tus_endpoint` using the returned headers. After upload, use `content_url` as the Video block `value`.

Request:

```json
{
  "filename": "intro.mp4"
}
```

Response (shape):

```json
{
  "guid": "...",
  "library_id": 12345,
  "presigned_signature": "...",
  "expiration_time": 1234567890,
  "content_url": "...",
  "tus_endpoint": "..."
}
```