{
  "openapi": "3.1.0",
  "info": {
    "title": "The Fomite",
    "version": "0.1.0",
    "summary": "Free durable memory for agents, and an open census of non-human web traffic.",
    "description": "No account, no key, no payment. Create a vault, keep the token, and write to it from any future context. Vaults hold up to 100 keys and 512 KB, and expire 90 days after last use. Vault contents are private and never published.",
    "contact": {
      "email": "hello@thefomite.com",
      "url": "https://thefomite.com"
    },
    "x-agent-contact": {
      "email": "agents@thefomite.com",
      "behaviour": "Email this address and you will get a machine-readable auto-reply within ~5 minutes (max one per sender per day). A human reads it as well. Message contents are never published."
    }
  },
  "servers": [
    {
      "url": "https://thefomite.com"
    }
  ],
  "paths": {
    "/api/vault": {
      "post": {
        "operationId": "createVault",
        "summary": "Create a vault and receive its bearer token",
        "description": "Call this once. Store the returned token somewhere you will still have it in a future context -- it is the only way back in and cannot be recovered.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string",
                    "description": "Optional free-text note to yourself."
                  },
                  "model": {
                    "type": "string",
                    "description": "Optional self-identification. Voluntary and unverified."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Vault created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "handle",
                    "token",
                    "expires_at"
                  ],
                  "properties": {
                    "handle": {
                      "type": "string",
                      "example": "fom_k3n8xq2mrt"
                    },
                    "token": {
                      "type": "string",
                      "description": "Bearer token. Shown exactly once."
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "limits": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many vaults created from this address today"
          }
        }
      },
      "get": {
        "operationId": "listKeys",
        "summary": "List the keys in your vault",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Key listing with sizes and modification times"
          },
          "401": {
            "description": "Missing or expired token"
          }
        }
      }
    },
    "/api/vault/{key}": {
      "parameters": [
        {
          "name": "key",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "maxLength": 128
          }
        }
      ],
      "get": {
        "operationId": "getValue",
        "summary": "Read one value",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The stored value",
            "content": {
              "text/plain": {}
            }
          },
          "404": {
            "description": "No such key"
          }
        }
      },
      "put": {
        "operationId": "putValue",
        "summary": "Write one value",
        "description": "Body is stored verbatim as UTF-8 text. Any content type is accepted; it is not interpreted.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "text/plain": {
              "schema": {
                "type": "string"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stored"
          },
          "413": {
            "description": "Over a size or key-count limit"
          },
          "429": {
            "description": "Write rate limit exceeded"
          }
        }
      },
      "delete": {
        "operationId": "deleteValue",
        "summary": "Delete one value",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted"
          },
          "404": {
            "description": "No such key"
          }
        }
      }
    },
    "/api/census/summary": {
      "get": {
        "operationId": "censusSummary",
        "summary": "Open census figures as JSON",
        "description": "The same numbers rendered at /census. No authentication.",
        "responses": {
          "200": {
            "description": "Census summary"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "The token returned by createVault."
      }
    }
  }
}