# Northstar Developer API

## GET /workspaces

List your team workspaces

Returns a bounded list of the caller’s accessible workspaces. This fictional contract uses a limit and optional plan filter.

- query limit&\#58; integer (optional)
- query plan&\#58; string (optional)

```sh
curl --request GET 'https://api.northstar.example/v1/workspaces?limit=12&plan=team' \
  --header "Authorization: Bearer ${API_TOKEN}"
```

### 200

Workspace list.

```json
{
  "data": [
    {
      "id": "wk_river_01",
      "name": "River Launch",
      "plan": "team",
      "members": 4
    }
  ],
  "total": 1
}
```

### 401

Authentication is missing or invalid.

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Provide an active API token."
  }
}
```

## POST /workspaces

Create a named workspace

Creates one workspace for the caller. This is a mutating request example; the reference never executes it.



```sh
curl --request POST https://api.northstar.example/v1/workspaces \
  --header "Authorization: Bearer ${API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data-raw '{"name": "River Launch", "plan": "team"}'
```

### 201

Workspace created.

```json
{
  "id": "wk_river_01",
  "name": "River Launch",
  "plan": "team",
  "members": 4
}
```

### 401

Authentication is missing or invalid.

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Provide an active API token."
  }
}
```

### 422

Input does not satisfy the workspace contract.

```json
{
  "error": {
    "code": "invalid-name",
    "message": "Provide a nonempty name of at most 80 characters."
  }
}
```

## GET /workspaces/{workspaceId}

Inspect a workspace

Read its name, plan and member count. Private access is determined by the actual service, outside this documentation generator.

- path workspaceId&\#58; string (required)

```sh
curl --request GET https://api.northstar.example/v1/workspaces/wk_river_01 \
  --header "Authorization: Bearer ${API_TOKEN}"
```

### 200

Workspace details.

```json
{
  "id": "wk_river_01",
  "name": "River Launch",
  "plan": "team",
  "members": 4
}
```

### 401

Authentication is missing or invalid.

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Provide an active API token."
  }
}
```

### 404

The workspace was not found.

```json
{
  "error": {
    "code": "not-found",
    "message": "Check the workspace ID."
  }
}
```

## PATCH /workspaces/{workspaceId}

Rename a workspace

Updates the workspace name. Review permissions and the intended mutation before running a downloaded example.

- path workspaceId&\#58; string (required)

```sh
curl --request PATCH https://api.northstar.example/v1/workspaces/wk_river_01 \
  --header "Authorization: Bearer ${API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data-raw '{"name": "River Launch / Review"}'
```

### 200

Updated workspace.

```json
{
  "id": "wk_river_01",
  "name": "River Launch / Review",
  "plan": "team",
  "members": 4
}
```

### 401

Authentication is missing or invalid.

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Provide an active API token."
  }
}
```

### 404

The workspace was not found.

```json
{
  "error": {
    "code": "not-found",
    "message": "Check the workspace ID."
  }
}
```

## DELETE /workspaces/{workspaceId}

Remove a workspace

A destructive request example requiring an explicit decision in the real service. No deletion occurs in this studio.

- path workspaceId&\#58; string (required)

```sh
curl --request DELETE https://api.northstar.example/v1/workspaces/wk_river_01 \
  --header "Authorization: Bearer ${API_TOKEN}"
```

### 204

Removed; no response body.

### 401

Authentication is missing or invalid.

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Provide an active API token."
  }
}
```

### 404

The workspace was not found.

```json
{
  "error": {
    "code": "not-found",
    "message": "Check the workspace ID."
  }
}
```

## GET /workspaces/{workspaceId}/activity

Read recent activity

Returns authored workspace activity records from this fictional interface.

- path workspaceId&\#58; string (required)

```sh
curl --request GET https://api.northstar.example/v1/workspaces/wk_river_01/activity \
  --header "Authorization: Bearer ${API_TOKEN}"
```

### 200

Recent activity.

```json
{
  "items": [
    {
      "id": "ev_01",
      "kind": "created",
      "message": "First review brief added."
    }
  ]
}
```

### 401

Authentication is missing or invalid.

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Provide an active API token."
  }
}
```

### 404

The workspace was not found.

```json
{
  "error": {
    "code": "not-found",
    "message": "Check the workspace ID."
  }
}
```

## GET /health

Check service health

A public health contract with a simple status response.



```sh
curl --request GET https://api.northstar.example/v1/health
```

### 200

Service health.

```json
{
  "status": "ok"
}
```