# Claim a paid subscription and retrieve the key (/docs/api-reference/v1/subscribe/claim/post)

`POST https://api.viralquery.com/v1/subscribe/claim`

Claim a paid subscription and retrieve the key

Operation ID: `claimSubscription`

OpenAPI document: https://viralquery.com/openapi.json

## Authentication

Public endpoint; no bearer token is required.

## Request

### Request body — application/json (required)

```json
{
  "type": "object",
  "properties": {
    "claimToken": {
      "type": "string",
      "pattern": "^claim_[A-Za-z0-9]{16,128}$"
    }
  },
  "required": [
    "claimToken"
  ],
  "additionalProperties": false
}
```

## Responses

### `200` — OK

**application/json**

```json
{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "completed"
          ]
        },
        "apiKey": {
          "type": "string"
        },
        "accountId": {
          "type": "string"
        },
        "plan": {
          "type": "string",
          "enum": [
            "viralquery"
          ]
        },
        "billingInterval": {
          "type": "string",
          "enum": [
            "monthly",
            "annual"
          ]
        }
      },
      "required": [
        "status",
        "apiKey",
        "accountId",
        "plan"
      ]
    },
    {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "pending"
          ]
        }
      },
      "required": [
        "status"
      ]
    },
    {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "invalid_token"
          ]
        }
      },
      "required": [
        "status"
      ]
    },
    {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "invalid_session"
          ]
        }
      },
      "required": [
        "status"
      ]
    },
    {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "already_claimed"
          ]
        },
        "accountId": {
          "type": "string"
        },
        "plan": {
          "type": "string",
          "enum": [
            "viralquery"
          ]
        },
        "billingInterval": {
          "type": "string",
          "enum": [
            "monthly",
            "annual"
          ]
        }
      },
      "required": [
        "status"
      ]
    }
  ]
}
```

### `400` — Invalid request (input failed validation)

**application/json**

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_request"
      ],
      "description": "Stable machine-readable error code."
    },
    "message": {
      "type": "string",
      "description": "Human-readable summary."
    },
    "issues": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "path",
          "message"
        ]
      },
      "description": "First-class Zod validation issues (path + message), not a stringified blob."
    }
  },
  "required": [
    "error",
    "message",
    "issues"
  ]
}
```

### `409` — Conflict or operation error

**application/json**

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "operation_error"
      ]
    },
    "message": {
      "type": "string",
      "description": "The operation failed while handling the request."
    }
  },
  "required": [
    "error",
    "message"
  ]
}
```

### `429` — Too Many Requests (rate limited)

**application/json**

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "rate_limited"
      ]
    },
    "message": {
      "type": "string"
    },
    "retryAfter": {
      "type": "number",
      "description": "Seconds to wait before retrying (mirrors the Retry-After header)."
    }
  },
  "required": [
    "error",
    "message",
    "retryAfter"
  ]
}
```

### `502` — Temporary upstream service error — safe to retry

**application/json**

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "temporary_service_error"
      ]
    },
    "message": {
      "type": "string",
      "description": "Temporary service error."
    },
    "retryable": {
      "type": "boolean",
      "enum": [
        true
      ],
      "description": "Safe to retry."
    }
  },
  "required": [
    "error",
    "message",
    "retryable"
  ]
}
```