# DDS Matchmaker API

> REST API behind DDS Matchmaker. Blog posts and the expert directory are open to
> read without credentials; everything else needs a bearer token.

Source: https://ddsmatchmaker.net/developers

## Reference

- [OpenAPI 3.0 spec](https://ddsmatchmaker.net/openapi.json): every operation, parameter and
  response schema. Also at https://api.ddsmatchmaker.net/openapi.json
- [Interactive docs](https://api.ddsmatchmaker.net/docs/): try requests in the browser
- [API catalog (RFC 9727)](https://ddsmatchmaker.net/.well-known/api-catalog)

## Base URL

https://api.ddsmatchmaker.net

All responses are JSON. Successful responses wrap the payload in `data`.

## Quickstart: no credentials

```sh
curl "https://api.ddsmatchmaker.net/blogs?page=1&limit=10"
curl "https://api.ddsmatchmaker.net/blogs/<slug>"
curl "https://api.ddsmatchmaker.net/experts?page=1&limit=10&search=implant"
curl "https://api.ddsmatchmaker.net/experts/<id>"
```

`GET /experts` also filters by `location`, `skills`, `tags`,
`availability`, `engagementType` and `sortBy`; see the spec for values.

## Authentication

Everything outside the open reads needs a JWT bearer token. Create an account at
https://app.ddsmatchmaker.net/register, then exchange its credentials for a token:

```sh
curl -X POST "https://api.ddsmatchmaker.net/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"..."}'
```

The token is at `data.token` in the response. Send it on every request:

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

An unverified email gets `403` with `"isEmailVerified": false`, and a fresh
one-time code is emailed automatically.

## Errors

Errors are JSON with the matching HTTP status, for example
`404 {"message":"Blog not found"}` or `401` on a missing or expired token.

## Rate limits

Every response carries IETF `RateLimit` and `RateLimit-Policy` headers
(currently 60 requests per 60 seconds), so clients can throttle themselves
before hitting a `429`.

## Support

support@networkdental.us