n0t1fy-dev Keys API

openapi: 3.2.0
info:
  title: N0t1fy Dev Keys API
  version: 0.2.0
  description: 'Operations tagged keys across 2 of this provider''s published API definitions: n0t1fy-dev-api-openapi.json, n0t1fy-dev-openapi.json. Each path carries the servers of the definition it was published in.'
tags:
- name: Keys
paths:
  /v1/test-keys:
    post:
      tags:
      - Keys
      summary: Get a test API key instantly, without an account
      description: 'Returns a `sk_test_` key immediately, with no sign-in. Test keys use the built-in fake provider: they never send a real SMS and never spend credits, so an AI agent can build and verify a complete integration unattended.


        A human can take over the project: they open the returned `claim_url` in a browser, sign in with GitHub or Google, and confirm. Anyone who opens it, signs in and confirms becomes the owner: give it only to the person who will own the project, and do not paste it into shared logs or tickets. The key you already have keeps working, but it stays a test key and still never sends a real SMS. To send real messages, the human creates an `sk_live_` key on the dashboard and your code switches to it. A claim by someone with no account yet gives their new account its free credits; a claim into an account they already have adds none.'
      operationId: create_test_key_v1_test_keys_post
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestKeyResponse'
        '429':
          description: '`rate_limited`: too many keys requested from this address this minute; retry in a minute. `daily_limit_reached`: today''s allowance of instant test keys is used up, for this address or for everyone; do not retry before the reset time named in the message (midnight UTC). Every `429` carries a `Retry-After` header (whole seconds, rounded up) and `error.retry_at` (ISO 8601 UTC): the same moment, when the limit frees.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          headers:
            Retry-After:
              description: Whole seconds until the limit frees, rounded up and at least 1.
              schema:
                type: integer
                minimum: 1
components:
  schemas:
    ApiErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorBody'
      type: object
      required:
      - error
      title: ApiErrorResponse
      description: Every error response in this API has this shape.
    TestKeyResponse:
      properties:
        api_key:
          type: string
          title: Api Key
          description: The key itself, shown only in this response. Store it now.
          examples:
          - REDACTED_STRIPE_KEY
        project_id:
          type: string
          title: Project Id
          description: The project this key belongs to.
        mode:
          type: string
          const: test
          title: Mode
          description: 'Always `test`: this key uses the fake provider and cannot deliver an SMS.'
        claim_url:
          type: string
          title: Claim Url
          description: 'For a human: open in a browser, sign in, and confirm to take ownership of this project. Anyone who opens it, signs in and confirms becomes the owner: give it only to the person who will own the project, and do not paste it into shared logs or tickets. The key above keeps working afterwards, but only as a test key: real SMS need an `sk_live_` key from the dashboard.'
        expires_at:
          type: string
          title: Expires At
          description: When `claim_url` stops working if nobody has used it. The key above is not affected.
        next_steps:
          type: string
          title: Next Steps
          description: What to do next, in one line, for a caller with no human attached.
      type: object
      required:
      - api_key
      - project_id
      - mode
      - claim_url
      - expires_at
      - next_steps
      title: TestKeyResponse
      description: An instantly issued test key, plus the link that turns it into a real account.
    ApiErrorBody:
      properties:
        code:
          type: string
          title: Code
          description: Stable machine-readable error code.
          examples:
          - invalid_recipient
        message:
          type: string
          title: Message
          description: Human-readable explanation, written to be actionable.
          examples:
          - 'The recipient must be a Georgian mobile number in E.164 format: +9955XXXXXXXX.'
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Request Id
          description: Echoes the `X-Request-Id` response header; quote it when reporting a problem.
          examples:
          - req_01J8XW7K2N9P4Q6R8S0T2V4W6X
        retry_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Retry At
          description: 'Only on a `429` (`rate_limited`, `daily_limit_reached`, `too_many_verifications`): when the limit frees, ISO 8601 UTC with a `Z` suffix, the same moment the `Retry-After` header counts down to. Show a countdown to it; do not retry before it. Absent from every other error.'
          examples:
          - '2026-10-16T12:35:00Z'
      type: object
      required:
      - code
      - message
      title: ApiErrorBody
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'An API key: `sk_test_…` (fake provider, never sends) or `sk_live_…`. Get a test key from `POST /v1/test-keys`.'
x-refined-from:
- n0t1fy-dev-api-openapi.json
- n0t1fy-dev-openapi.json