{
  "openapi": "3.1.0",
  "info": {
    "title": "land API",
    "version": "1",
    "summary": "The land API: the public signing keys, and who a land key belongs to.",
    "description": "land merges each finished branch with main and reruns only the test commands that change can affect. Agents use land through the land command-line tool (see https://useland.dev/docs), not by calling this API directly. This description covers the public keys used to check that a commit was landed by land (`land verify`), which need no sign-in, and the identity endpoint, which shows how signed-in requests and errors look. The rest of the API serves the land CLI and the dashboard. The endpoints described here report errors as JSON: `{\"error\": {\"code\": \"...\", \"message\": \"...\"}}`. Versioning and deprecation: the API is versioned in its address (/v1). A breaking change gets a new version, and the old one keeps working for at least 90 days after its removal is announced at https://useland.dev/docs#verify.",
    "contact": {
      "name": "Ataraxy Labs, Inc.",
      "email": "rohan@ataraxy-labs.com",
      "url": "https://useland.dev/contact"
    },
    "termsOfService": "https://useland.dev/terms"
  },
  "externalDocs": {
    "description": "land docs: setup, verdicts, checking a commit, limits",
    "url": "https://useland.dev/docs"
  },
  "servers": [
    {
      "url": "https://api.useland.dev",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "verification",
      "description": "Checking that a commit was landed by land"
    },
    {
      "name": "account",
      "description": "The signed-in account"
    }
  ],
  "paths": {
    "/v1/land/keys": {
      "get": {
        "operationId": "getLandVerificationKeys",
        "tags": [
          "verification"
        ],
        "summary": "Get land's public signing keys",
        "description": "Returns the public keys land signs its verdicts with, and the ids of any keys that have been revoked. Save the response to a file and pass it to `land verify HEAD --pubkey land-keys.json --protected main` to check a commit offline. No sign-in is needed.",
        "security": [],
        "responses": {
          "200": {
            "description": "The current public keys and the revoked key ids.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KeySet"
                },
                "example": {
                  "keys": [
                    {
                      "alg": "ed25519",
                      "key_id": "f0dcf725a8f6f1eec85ba49bfb870dc2",
                      "not_after": null,
                      "public": "X1+DJdXNcbOvMFlewnDnRkpYEs8bwq8QhznbjigRYTU="
                    }
                  ],
                  "revoked": []
                }
              }
            }
          }
        }
      }
    },
    "/v1/land/identity": {
      "get": {
        "operationId": "getLandIdentity",
        "tags": [
          "account"
        ],
        "summary": "Show who a land key belongs to",
        "description": "Returns the account behind the key in the Authorization header. Use it to check that a key or LAND_TOKEN is valid before running `land merge`.",
        "security": [
          {
            "landKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "The key is valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Identity"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "KeySet": {
        "type": "object",
        "description": "land's public signing keys.",
        "required": [
          "keys",
          "revoked"
        ],
        "properties": {
          "keys": {
            "type": "array",
            "description": "The public keys verdicts may be signed with.",
            "items": {
              "$ref": "#/components/schemas/PublicKey"
            }
          },
          "revoked": {
            "type": "array",
            "description": "Keys that must no longer be trusted.",
            "items": {
              "type": "string",
              "description": "The id of a revoked key."
            }
          }
        }
      },
      "PublicKey": {
        "type": "object",
        "description": "One public signing key.",
        "required": [
          "alg",
          "key_id",
          "public"
        ],
        "properties": {
          "alg": {
            "type": "string",
            "description": "The signature algorithm.",
            "examples": [
              "ed25519"
            ]
          },
          "key_id": {
            "type": "string",
            "description": "The key's id, as named in a signed verdict."
          },
          "not_after": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the key stops being valid, or null if it has no end date."
          },
          "public": {
            "type": "string",
            "description": "The public key, base64."
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "The shape of an error from the endpoints described here.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "A stable, machine-readable reason.",
                "examples": [
                  "unauthorized"
                ]
              },
              "message": {
                "type": "string",
                "description": "What went wrong, in words.",
                "examples": [
                  "Missing or invalid Authorization header"
                ]
              }
            }
          }
        }
      },
      "Identity": {
        "type": "object",
        "description": "Who a land key belongs to. Other fields may be present.",
        "properties": {
          "owner": {
            "type": "string",
            "description": "The account the key belongs to."
          }
        }
      }
    },
    "securitySchemes": {
      "landKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "A land key from `land login`, or a LAND_TOKEN created in the dashboard, sent as `Authorization: Bearer <key>`."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing or the key is not valid.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header"
              }
            }
          }
        }
      }
    }
  }
}
