# Invite someone to a workspace

> Invite an email address into a workspace.

<div class="g1t-endpoint"><span class="g1t-method" data-method="post">POST</span><code>/workspaces/{workspace}/invitations</code></div>

It always makes an invite bound to that address and emails it the link, so the answer never says whether the address has a g1t account. Without one, accepting makes the account and joins the workspace in one step, and uses one of the workspace's granted invites, or else one of yours. With one, it costs nothing, and they join when they accept. To add someone by username at once, use the workspace's People page. Owners only.

`kind` is `workspace` when the address already has a g1t account (`charged_to` is then `none`), and `account` when accepting makes one. Both answers look alike to the caller on purpose: the invite is emailed either way.

- **Authentication:** Required. Send an [access token](/reference/api/#authentication) as `Authorization: Bearer`.
- **MCP tool:** [`invite_member`](/reference/mcp/), with the same inputs

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workspace` | string | Yes | The workspace's slug, e.g. "flagon-io". |

## Body parameters

Send a JSON object. Names are `snake_case`, as in responses; the `camelCase` spelling is accepted too.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | Yes | The address to invite. |

## Example request

```sh
curl -X POST https://api.g1t.sh/workspaces/flagon-io/invitations \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com"
  }'
```

## Example response

A successful request answers `200` with:

```json
{
  "id": "inv_01kp2x7m8n9q0r1s2t3v4w5x6y",
  "code": "g1t-k7m2-q9xd-4hpw-…",
  "hint": "g1t-k7m2",
  "email": "ada@example.com",
  "kind": "account",
  "workspace": "acme-labs",
  "status": "pending",
  "charged_to": "workspace",
  "invited_by": "syntaqx",
  "redeemed_by": null,
  "created_at": "2026-10-05T17:00:00.000Z",
  "expires_at": "2026-11-04T17:00:00.000Z",
  "redeemed_at": null,
  "revoked_at": null
}
```

## Errors

A failed request answers with one of these statuses and a body like `{"error": {"code": "not_found", "message": "Repository not found."}}`. See [errors](/reference/api/#errors).

| Status | Code | When |
| --- | --- | --- |
| 401 | `unauthenticated` | A token is required, or the one sent is not valid. |
| 403 | `forbidden` | The token is valid but not allowed to do this, such as a member-only change or an agent token outside its repository. |
| 404 | `not_found` | It does not exist, or you cannot see it. |
| 409 | `conflict` | The request conflicts with the current state. |
| 422 | `invalid` | The input is not valid. `message` says which field and why. |