# Lookup

Public lookups: an address's card, WebFinger, health and this document.

Calls go to https://address.seleya.ai/api. Errors are `{"error": {"code", "message"}}` with the HTTP status: https://address.seleya.ai/docs/reference/errors.md

## WebFinger

`GET /.well-known/webfinger`, called with 

Resolves acct:name@domain to the address's public card (RFC 7033). Served on each mail domain and on the API host.

| Parameter | Type | | |
| --- | --- | --- | --- |
| `resource` | string, in query | optional | acct:name@domain |

```bash
curl https://address.seleya.ai/api/.well-known/webfinger
```

```python
import os, requests

r = requests.get(
    "https://address.seleya.ai/api/.well-known/webfinger",
)
print(r.status_code, r.json())
```

```typescript
const r = await fetch("https://address.seleya.ai/api/.well-known/webfinger", {
  method: "GET",
});
console.log(r.status, await r.json());
```

Answers:

- 200: Done
- 400: The request is malformed
- 404: Not found, or not yours to see

## This document

`GET /openapi.json`, called with 

The API described in OpenAPI 3.1.

```bash
curl https://address.seleya.ai/api/openapi.json
```

```python
import os, requests

r = requests.get(
    "https://address.seleya.ai/api/openapi.json",
)
print(r.status_code, r.json())
```

```typescript
const r = await fetch("https://address.seleya.ai/api/openapi.json", {
  method: "GET",
});
console.log(r.status, await r.json());
```

Answers:

- 200: Done

## An address's public card

`GET /v1/cards/{a}`, called with 

Who stands behind an address, whether that owner is verified, how to reach it and how to stop it mailing you.

| Parameter | Type | | |
| --- | --- | --- | --- |
| `a` | string, in path | required | The address, such as desk@acme.seleya.email. |

```bash
curl https://address.seleya.ai/api/v1/cards/desk@acme.seleya.email
```

```python
import os, requests

r = requests.get(
    "https://address.seleya.ai/api/v1/cards/desk@acme.seleya.email",
)
print(r.status_code, r.json())
```

```typescript
const r = await fetch("https://address.seleya.ai/api/v1/cards/desk@acme.seleya.email", {
  method: "GET",
});
console.log(r.status, await r.json());
```

Answers:

- 200: Done
- 404: Not found, or not yours to see

| Field (200) | Type | | |
| --- | --- | --- | --- |
| `address` | string | required |  |
| `display_name` | string | required |  |
| `owner` | object | required |  |
| `reach` | object | optional |  |
| `stop` | object | optional |  |
| `capabilities` | Capabilities | optional |  |

```json
{
  "address": "ct-a@beta.com",
  "display_name": "Contract agent A",
  "owner": {
    "name": "Acme (test company)",
    "proven_domain": "beta.com",
    "type": "company",
    "verification": "domain"
  },
  "reach": {
    "api": "https://address.seleya.ai/api/v1",
    "email": "ct-a@beta.com"
  },
  "stop": {
    "email": "ct-a@beta.com",
    "how": "Reply \"stop\" to any message from this address, and it never mails you again."
  }
}
```

## Health

`GET /v1/health`, called with 

Answers when the API is up.

```bash
curl https://address.seleya.ai/api/v1/health
```

```python
import os, requests

r = requests.get(
    "https://address.seleya.ai/api/v1/health",
)
print(r.status_code, r.json())
```

```typescript
const r = await fetch("https://address.seleya.ai/api/v1/health", {
  method: "GET",
});
console.log(r.status, await r.json());
```

Answers:

- 200: Done

| Field (200) | Type | | |
| --- | --- | --- | --- |
| `ok` | boolean | required |  |

```json
{
  "ok": true
}
```

## WebFinger on the API host

`GET /v1/webfinger`, called with 

The same lookup, at the API host, for companies' own domains that point here.

| Parameter | Type | | |
| --- | --- | --- | --- |
| `resource` | string, in query | optional | acct:name@domain |

```bash
curl https://address.seleya.ai/api/v1/webfinger
```

```python
import os, requests

r = requests.get(
    "https://address.seleya.ai/api/v1/webfinger",
)
print(r.status_code, r.json())
```

```typescript
const r = await fetch("https://address.seleya.ai/api/v1/webfinger", {
  method: "GET",
});
console.log(r.status, await r.json());
```

Answers:

- 200: Done
- 400: The request is malformed
- 404: Not found, or not yours to see