{
  "openapi": "3.1.0",
  "info": {
    "title": "shapes agent API",
    "version": "1.0.0",
    "description": "Build private link-in-bio pages for people. Drafts are free, private and kept for 7 days; the person claims one with the claimUrl and only they can publish. Full guide: https://shapes.bio/llms-full.txt",
    "contact": {
      "email": "support@shapes.bio",
      "url": "https://shapes.bio/developers/agents"
    }
  },
  "servers": [
    {
      "url": "https://shapes.bio/api/agent/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "editToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "The editToken returned when the draft was created"
      }
    }
  },
  "paths": {
    "/guide": {
      "get": {
        "operationId": "getGuide",
        "summary": "Design rules, blocks and operations (markdown)",
        "responses": {
          "200": {
            "description": "Markdown",
            "content": {
              "text/markdown": {}
            }
          }
        }
      }
    },
    "/schema": {
      "get": {
        "operationId": "getSchema",
        "summary": "Machine-readable document schema",
        "responses": {
          "200": {
            "description": "Schema",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/looks": {
      "get": {
        "operationId": "listLooks",
        "summary": "The six curated looks",
        "responses": {
          "200": {
            "description": "Looks",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/handles/{handle}": {
      "get": {
        "operationId": "checkHandle",
        "summary": "Check whether an address is free (not reserved)",
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Status",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/drafts": {
      "post": {
        "operationId": "createDraft",
        "summary": "Build a private page draft",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 80,
                    "description": "Their name or business"
                  },
                  "bio": {
                    "type": "string",
                    "maxLength": 400
                  },
                  "preset": {
                    "type": "string",
                    "enum": [
                      "shapes",
                      "paper",
                      "midnight",
                      "studio",
                      "rose",
                      "clay"
                    ]
                  },
                  "socials": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "platform": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "platform",
                        "url"
                      ]
                    }
                  },
                  "links": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "title": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        },
                        "subtitle": {
                          "type": "string"
                        },
                        "layout": {
                          "type": "string",
                          "enum": [
                            "classic",
                            "thumbnail",
                            "featured"
                          ]
                        },
                        "thumbnail": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "title",
                        "url"
                      ]
                    }
                  },
                  "blocks": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string"
                        },
                        "props": {
                          "type": "object"
                        },
                        "children": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      },
                      "required": [
                        "type"
                      ]
                    }
                  },
                  "avatar": {
                    "type": "string",
                    "description": "https image URL"
                  },
                  "starter": {
                    "type": "boolean",
                    "description": "Start from the curated example page for the look"
                  },
                  "theme": {
                    "type": "object"
                  },
                  "meta": {
                    "type": "object",
                    "properties": {
                      "title": {
                        "type": "string"
                      },
                      "description": {
                        "type": "string"
                      }
                    }
                  },
                  "ops": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "doc": {
                    "type": "object",
                    "description": "A whole page document instead of the fields above"
                  },
                  "suggestedHandle": {
                    "type": "string"
                  },
                  "client": {
                    "type": "string",
                    "description": "Name of your assistant or app"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "draftId": {
                      "type": "string"
                    },
                    "revision": {
                      "type": "integer"
                    },
                    "previewUrl": {
                      "type": "string"
                    },
                    "claimUrl": {
                      "type": "string"
                    },
                    "editToken": {
                      "type": "string"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "nextSteps": {
                      "type": "string"
                    },
                    "blockCount": {
                      "type": "integer"
                    },
                    "suggestedHandle": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A readable error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "opIndex": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "A readable error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "opIndex": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/drafts/{draftId}": {
      "get": {
        "operationId": "getDraft",
        "summary": "Read a draft",
        "security": [
          {
            "editToken": []
          }
        ],
        "parameters": [
          {
            "name": "draftId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Draft",
            "content": {
              "application/json": {}
            }
          },
          "401": {
            "description": "A readable error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "opIndex": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "A readable error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "opIndex": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateDraft",
        "summary": "Change a draft with operations",
        "security": [
          {
            "editToken": []
          }
        ],
        "parameters": [
          {
            "name": "draftId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ops": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "baseRevision": {
                    "type": "integer"
                  },
                  "doc": {
                    "type": "object"
                  },
                  "suggestedHandle": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "draftId": {
                      "type": "string"
                    },
                    "revision": {
                      "type": "integer"
                    },
                    "previewUrl": {
                      "type": "string"
                    },
                    "claimUrl": {
                      "type": "string"
                    },
                    "editToken": {
                      "type": "string"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "nextSteps": {
                      "type": "string"
                    },
                    "blockCount": {
                      "type": "integer"
                    },
                    "suggestedHandle": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A readable error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "opIndex": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "A readable error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "opIndex": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "A readable error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "opIndex": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "A readable error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "opIndex": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "A readable error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "opIndex": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}