Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
279 changes: 279 additions & 0 deletions API-DOCUMENTATION.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,279 @@
# API Reference Documentation Architecture

Check warning on line 1 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L1

'API Reference Documentation Architecture' should use sentence-style capitalization.

This document outlines how the API reference section is built, maintained, and potential improvements.

Check warning on line 3 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L3

'is built' may be passive voice. Use active voice if you can.

Check warning on line 3 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L3

Try to avoid using 'is'.

Check warning on line 3 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L3

In general, use active voice instead of passive voice ('is built').

## Current Architecture

Check warning on line 5 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L5

'Current Architecture' should use sentence-style capitalization.

### Overview

The API reference documentation uses Mintlify's OpenAPI integration. The system has three main components:

Check warning on line 9 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L9

Did you really mean 'Mintlify's'?

```
┌─────────────────────────────────────────────────────────────────────────┐
│ docs.json │
│ - Defines "API" tab with openapi reference │
│ - Contains 22 navigation groups │
│ - Lists all 132 page references │
└─────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────┐
│ api-reference/openapi.json │
│ - 514KB OpenAPI 3.0.0 specification │
│ - Auto-updated from https://api.checklyhq.com/openapi.json │
│ - Contains 94 unique API paths │
│ - Source of truth for all endpoint documentation │
└─────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────┐
│ api-reference/{category}/*.mdx │
│ - 132 stub files across 29 subdirectories │
│ - Minimal content: just frontmatter with `openapi: METHOD /path` │
│ - Mintlify auto-generates full documentation from OpenAPI spec │
└─────────────────────────────────────────────────────────────────────────┘
```

### File Structure

Check warning on line 37 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L37

'File Structure' should use sentence-style capitalization.

```
api-reference/
├── openapi.json # OpenAPI 3.0.0 spec (auto-updated)
├── accounts/ # 3 files
├── alert-channels/ # 6 files
├── alert-notifications/ # 1 file
├── analytics/ # 8 files
├── badges/ # 2 files
├── check-alerts/ # 2 files
├── check-groups/ # 9 files
├── check-results/ # 3 files
├── check-sessions/ # 3 files
├── check-status/ # 2 files
├── checks/ # 13 files
├── client-certificates/ # 4 files
├── dashboards/ # 5 files
├── environment-variables/ # 5 files
├── heartbeats/ # 5 files
├── incident-updates/ # 3 files
├── incidents/ # 4 files
├── location/ # 1 file
├── maintenance-windows/ # 5 files
├── monitors/ # 2 files
├── opentelemetry/ # 1 file (not in nav)
├── private-locations/ # 8 files
├── reporting/ # 1 file
├── runtimes/ # 2 files
├── snippets/ # 5 files
├── static-ips/ # 6 files
├── status-page-incidents/ # 10 files
├── status-page-services/ # 5 files
├── status-pages/ # 7 files
└── triggers/ # 6 files
```

### MDX File Format

Check warning on line 74 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L74

Spell out 'MDX', if it's unfamiliar to the audience.

Check warning on line 74 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L74

'MDX File Format' should use sentence-style capitalization.

Each MDX file is a minimal stub that references an OpenAPI path:

Check warning on line 76 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L76

Spell out 'MDX', if it's unfamiliar to the audience.

Check warning on line 76 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L76

Try to avoid using 'is'.

```yaml
---
openapi: get /v1/accounts
---
```

Optional fields:
- `deprecated: true` - marks endpoint as deprecated

Mintlify automatically generates:

Check warning on line 87 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L87

Did you really mean 'Mintlify'?
- Endpoint description
- HTTP method badge (GET/POST/PUT/DELETE)

Check warning on line 89 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L89

Use parentheses judiciously.

Check warning on line 89 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L89

Spell out 'PUT', if it's unfamiliar to the audience.
- Request parameters table
- Request body schema
- Response schemas for all status codes
- Code examples (cURL, JavaScript, Python)

Check warning on line 93 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L93

Use parentheses judiciously.
- "Try it" interactive playground

### docs.json Configuration

Check warning on line 96 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L96

'docs.json Configuration' should use sentence-style capitalization.

Located at lines 577-863, the API tab is configured as:

Check warning on line 98 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L98

'is configured' may be passive voice. Use active voice if you can.

Check warning on line 98 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L98

In general, use active voice instead of passive voice ('is configured').

Check warning on line 98 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L98

Try to avoid using 'is'.

```json
{
"tab": "API",
"openapi": "api-reference/openapi.json",
"groups": [
{
"group": "Accounts",
"pages": [
"api-reference/accounts/fetch-user-accounts",
"api-reference/accounts/fetch-current-account-details",
"api-reference/accounts/fetch-a-given-account-details"
]
},
// ... 21 more groups
]
}
```

### Automation

#### GitHub Actions Workflow

Check warning on line 120 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L120

'GitHub Actions Workflow' should use sentence-style capitalization.

**File:** `.github/workflows/update-api-spec.yml`

- **Schedule:** Runs every 48 hours (cron: `0 2 */2 * *`)

Check warning on line 124 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L124

Use parentheses judiciously.

Check warning on line 124 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L124

Did you really mean 'cron'?
- **Trigger:** Also supports manual `workflow_dispatch`
- **Process:**
1. Fetches spec from `https://api.checklyhq.com/openapi.json`
2. Converts HTML tags in descriptions to Markdown
3. Validates with `mintlify openapi-check`
4. Commits directly to `main` if changed

#### Update Script

Check warning on line 132 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L132

'Update Script' should use sentence-style capitalization.

**File:** `update-api-spec.sh`

```bash
# Key operations:
1. Fetch live spec from API
2. Convert HTML to Markdown (<a> → [](), <br> → \n, <b> → **, <code> → `)
3. Validate OpenAPI spec
4. Replace local file
```

## Current Issues

### 1. MDX/Navigation Sync Issues

Check warning on line 146 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L146

'1. MDX/Navigation Sync Issues' should use sentence-style capitalization.

Check warning on line 146 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L146

Spell out 'MDX', if it's unfamiliar to the audience.

The 132 MDX files correctly map to OpenAPI operations (method + path). A single path like `/v1/checks/{id}` can have multiple methods (GET, PUT, DELETE), each requiring its own MDX file.

Check warning on line 148 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L148

Spell out 'MDX', if it's unfamiliar to the audience.

Check warning on line 148 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L148

Use parentheses judiciously.

Check warning on line 148 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L148

'multiple' is too wordy.

Check warning on line 148 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L148

Use parentheses judiciously.

Check warning on line 148 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L148

Spell out 'PUT', if it's unfamiliar to the audience.

Check warning on line 148 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L148

Spell out 'MDX', if it's unfamiliar to the audience.

| Metric | Count |
|--------|-------|
| MDX files | 132 |

Check warning on line 152 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L152

Spell out 'MDX', if it's unfamiliar to the audience.
| Unique API paths in MDX | 90 |

Check warning on line 153 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L153

Spell out 'MDX', if it's unfamiliar to the audience.
| HTTP methods breakdown | GET: 67, POST: 26, PUT: 21, DELETE: 18 |

Check warning on line 154 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L154

Spell out 'PUT', if it's unfamiliar to the audience.

#### Orphaned MDX Files (exist but not in navigation)

Check warning on line 156 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L156

'Orphaned MDX Files (exist but not in navigation)' should use sentence-style capitalization.

Check warning on line 156 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L156

Spell out 'MDX', if it's unfamiliar to the audience.

Check warning on line 156 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L156

Use parentheses judiciously.

| File | OpenAPI Reference |
|------|-------------------|
| `api-reference/opentelemetry/post-accounts-metrics.mdx` | `post /accounts/{accountId}/metrics` |

#### Broken Navigation Links (in docs.json but no MDX file)

Check warning on line 162 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L162

'Broken Navigation Links (in docs.json but no MDX file)' should use sentence-style capitalization.

Check warning on line 162 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L162

Use parentheses judiciously.

Check warning on line 162 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L162

Spell out 'MDX', if it's unfamiliar to the audience.

| Missing File |
|--------------|
| `api-reference/snippets/list-all-snippets.mdx` |
| `api-reference/snippets/create-a-snippet.mdx` |
| `api-reference/snippets/retrieve-a-snippet.mdx` |
| `api-reference/snippets/update-a-snippet.mdx` |
| `api-reference/snippets/delete-a-snippet.mdx` |
| `api-reference/detect/uptime-monitoring/url-monitors/overview.mdx` |
| `api-reference/detect/uptime-monitoring/url-monitors/configuration.mdx` |

**Summary:** 1 orphaned file + 7 broken links = 8 total issues

### 2. Navigation Inconsistencies

- 22 groups in docs.json, 29 subdirectories in filesystem
- The `opentelemetry/` directory has 1 file but no group in docs.json
- The `snippets/` group exists in docs.json but files have different names or are missing

Check warning on line 180 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L180

Try to avoid using 'are'.

### 3. Naming Inconsistencies

- Mixed patterns: `list-all-*` vs `lists-all-*`
- Some verbose names: `retrieve-all-checks-in-a-specific-group-with-group-settings-applied`
- Inconsistent verb usage: `fetch` vs `retrieve` vs `get` vs `list`

### 4. Orphaned Files

Check warning on line 188 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L188

'4. Orphaned Files' should use sentence-style capitalization.

- Multiple backup files: `openapi.json.backup*`

Check warning on line 190 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L190

'Multiple' is too wordy.
- Directories with files not in docs.json navigation

### 5. Manual Synchronization Required

Check warning on line 193 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L193

'5. Manual Synchronization Required' should use sentence-style capitalization.

- When API spec adds/removes endpoints, MDX files and docs.json must be manually updated

Check warning on line 195 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L195

Spell out 'MDX', if it's unfamiliar to the audience.

Check warning on line 195 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L195

Try to avoid using 'be'.
- No automation for generating new MDX stubs or updating navigation

Check warning on line 196 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L196

Spell out 'MDX', if it's unfamiliar to the audience.

## Potential Improvements

### Short-term

1. **Audit and cleanup**
- Remove orphaned MDX files that don't map to OpenAPI paths

Check warning on line 203 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L203

Spell out 'MDX', if it's unfamiliar to the audience.
- Delete backup files
- Add missing pages to docs.json or remove unused directories

2. **Fix broken links**
- Verify all docs.json page references have corresponding MDX files

Check warning on line 208 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L208

Spell out 'MDX', if it's unfamiliar to the audience.
- Verify all MDX `openapi:` references exist in openapi.json

Check warning on line 209 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L209

Spell out 'MDX', if it's unfamiliar to the audience.

3. **Standardize naming**
- Establish naming conventions (e.g., always `list-` not `lists-`)

Check warning on line 212 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L212

Use parentheses judiciously.

Check warning on line 212 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L212

Use 'for example' instead of 'e.g.'.
- Keep names concise but descriptive

### Medium-term

4. **Automate MDX generation**

Check warning on line 217 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L217

Spell out 'MDX', if it's unfamiliar to the audience.
- Script to generate MDX stubs from OpenAPI paths

Check warning on line 218 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L218

Spell out 'MDX', if it's unfamiliar to the audience.
- Script to update docs.json navigation from OpenAPI tags
- Run as part of the update-api-spec workflow

5. **Leverage OpenAPI tags**
- OpenAPI spec likely has tags for grouping endpoints
- Could auto-generate navigation structure from tags

### Long-term

6. **Consider Mintlify auto-generation**
- Mintlify can auto-generate pages from OpenAPI spec

Check warning on line 229 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L229

Did you really mean 'Mintlify'?
- May eliminate need for individual MDX files

Check warning on line 230 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L230

'eliminate' is too wordy.

Check warning on line 230 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L230

Spell out 'MDX', if it's unfamiliar to the audience.
- Trade-off: less control over URL structure and organization

## API Endpoints Summary

Check warning on line 233 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L233

'API Endpoints Summary' should use sentence-style capitalization.

### By Category (from OpenAPI spec paths)

Check warning on line 235 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L235

Use parentheses judiciously.

| Category | Endpoints |
|----------|-----------|
| accounts | 3 |
| alert-channels | 3 |
| alert-notifications | 1 |
| analytics | 8 |
| badges | 2 |
| check-alerts | 2 |
| check-groups | 4 |
| check-results | 2 |
| check-sessions | 3 |
| check-statuses | 2 |
| checks | 18 |
| client-certificates | 2 |
| dashboards | 2 |
| incidents | 4 |
| locations | 1 |
| maintenance-windows | 2 |
| private-locations | 5 |
| reporting | 1 |
| runtimes | 2 |

Check warning on line 257 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L257

Did you really mean 'runtimes'?
| snippets | 2 |
| static-ips | 6 |
| status-pages | 12 |
| triggers | 2 |
| variables | 2 |

## Related Files

Check warning on line 264 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L264

'Related Files' should use sentence-style capitalization.

| File | Purpose |
|------|---------|
| `docs.json` | Main config, API nav at lines 577-863 |

Check warning on line 268 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L268

Did you really mean 'config'?
| `api-reference/openapi.json` | OpenAPI 3.0.0 specification |
| `update-api-spec.sh` | Script to fetch and process spec |
| `.github/workflows/update-api-spec.yml` | Automation workflow |

## Questions to Resolve

Check warning on line 273 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L273

'Questions to Resolve' should use sentence-style capitalization.

1. Should we automate MDX stub generation when the OpenAPI spec changes?

Check warning on line 275 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L275

Try to avoid using first-person plural like 'we'.

Check warning on line 275 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L275

Spell out 'MDX', if it's unfamiliar to the audience.
2. Should we consolidate some navigation groups (22 seems high)?

Check warning on line 276 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L276

Try to avoid using first-person plural like 'we'.

Check warning on line 276 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L276

'consolidate' is too wordy.

Check warning on line 276 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L276

Use parentheses judiciously.
3. Is the opentelemetry endpoint intentionally hidden from navigation?

Check warning on line 277 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L277

Try to avoid using 'Is'.

Check warning on line 277 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L277

Did you really mean 'opentelemetry'?
4. Should deprecated endpoints be removed or kept for backwards compatibility?

Check warning on line 278 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L278

Try to avoid using 'be'.

Check warning on line 278 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L278

In general, use active voice instead of passive voice ('be removed').

Check warning on line 278 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L278

'be removed' may be passive voice. Use active voice if you can.
5. Would Mintlify's auto-generation feature be preferable to manual MDX files?

Check warning on line 279 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L279

Did you really mean 'Mintlify's'?

Check warning on line 279 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L279

Try to avoid using 'be'.

Check warning on line 279 in API-DOCUMENTATION.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

API-DOCUMENTATION.md#L279

Spell out 'MDX', if it's unfamiliar to the audience.
1 change: 1 addition & 0 deletions api-reference/accounts/fetch-a-given-account-details.mdx
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: get /v1/accounts/{accountId}
title: Get specific account details
---
1 change: 1 addition & 0 deletions api-reference/accounts/fetch-current-account-details.mdx
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: get /v1/accounts/me
title: Get current account details
---
1 change: 1 addition & 0 deletions api-reference/accounts/fetch-user-accounts.mdx
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: get /v1/accounts
title: Get all account details
---
1 change: 1 addition & 0 deletions api-reference/analytics/api-checks.mdx
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: get /v1/analytics/api-checks/{id}
title: Get API Check analytics
---
1 change: 1 addition & 0 deletions api-reference/badges/get-v1badgeschecks.mdx
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: get /v1/badges/checks/{checkId}
title: Get badge for a check
---
1 change: 1 addition & 0 deletions api-reference/badges/get-v1badgesgroups.mdx
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: get /v1/badges/groups/{groupId}
title: Get badge for a group
---
1 change: 1 addition & 0 deletions api-reference/checks/create-a-tcp-check.mdx
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: post /v1/checks/tcp
title: Create a TCP monitor
---
1 change: 1 addition & 0 deletions api-reference/checks/update-an-tcp-check.mdx
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: put /v1/checks/tcp/{id}
title: Update a TCP monitor
---
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: post /v1/client-certificates
title: Create new client certificate
---
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: delete /v1/client-certificates/{id}
title: Delete existing client certificate
---
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: get /v1/client-certificates
title: List client certificates
---
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: get /v1/client-certificates/{id}
title: List specific client certificate
---
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: post /v1/variables
title: Create an environment variable
---
1 change: 1 addition & 0 deletions api-reference/heartbeats/create-a-heartbeat-check.mdx
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: post /v1/checks/heartbeat
title: Create a heartbeat check
---
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: get /v1/checks/heartbeats/{checkId}/events
title: List events for a heartbeat
---
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: get /v1/checks/heartbeats/{checkId}/events/{id}
title: List a specific heartbeat event
---
1 change: 1 addition & 0 deletions api-reference/heartbeats/get-heartbeat-availability.mdx
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: get /v1/checks/heartbeats/{checkId}/availability
title: Get heartbeat availability
---
1 change: 1 addition & 0 deletions api-reference/heartbeats/update-a-heartbeat-check.mdx
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: put /v1/checks/heartbeat/{id}
title: Update a heartbeat check
---
1 change: 1 addition & 0 deletions api-reference/monitors/create-a-url-monitor.mdx
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: post /v1/checks/url
title: Create a URL monitor
---
1 change: 1 addition & 0 deletions api-reference/monitors/update-an-url-monitor.mdx
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
openapi: put /v1/checks/url/{id}
title: Update a URL monitor
---
Loading