---
title: "Start an ownership claim; returns proof instructions and a one-time verify secret"
method: POST
path: "/claims"
tags: ["claims"]
---

# Start an ownership claim; returns proof instructions and a one-time verify secret

`POST /claims`

## Request

- Base URL: `https://wellknown.network/api/v1`
- URL: `https://wellknown.network/api/v1/claims`
- Auth: one of:
  - none
  - HTTP bearer

## Request body

- ClaimStart
  - `agent` string, required: Handle or id.
  - `method` 'dns_txt' | 'well_known_file' | 'repo_file' | 'github_owner', required: github_owner verifies instantly when the key's developer signed in with the GitHub account that owns the repository (or is a public member of the owning organisation).
  - `target` string: Domain, host[:port], repo key or GitHub owner; required only when the record offers several for the method.

## Response `200`

OK

- ClaimStartResponse
  - `claim` Claim
    - `id` string
    - `agent` object
      - `id` string
      - `handle` string
      - `url` string
    - `method` string
    - `target` string
    - `status` 'pending' | 'verified' | 'failed' | 'expired' | 'revoked'
    - `attempts` integer
    - `lastError` string, nullable
    - `expiresAt` string, date-time
    - `instructions` object
      - `title` string
      - `steps` string[]
      - `snippet` string
    - `verify` object
      - `url` string
      - `method` string
      - `authorization` string: Bearer <verifySecret>; shown only in the start response.
  - `note` string

## Other responses

- `404`: Error
- `409`: Error
- `422`: Error
- `429`: Rate limited; see Retry-After and X-RateLimit-* headers.

---

[API](https://skmtc.dev/wellknown/apis/wellknown-api.md) · [All operations](https://skmtc.dev/wellknown/apis/wellknown-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wellknown/apis/wellknown-api/revisions/8a177fdcd434?raw)