---
updatedAt: 2026-09-25T23:33:12.000Z
agentTools:
  projectIndex: https://docs.opensea.io/llms.txt
---

# Upload drop metadata to IPFS

Uploads every saved item's media and metadata to IPFS, then saves the resulting folder as the drop's draft base URI. Run it after POST /api/v2/drops/{slug}/items/media/save-batch; the drop needs at least one item. It does not change the contract: call POST /api/v2/drops/{slug}/publish once it completes.

This is the reveal. The base URI it writes points at the real item metadata, so a drop published after it has completed is revealed as soon as it is live. To reveal later, publish without running it (showing the prereveal item from POST /api/v2/drops/{slug}/prereveal-item), then run it and publish again when ready.

Only ERC-721 SeaDrop V1 drops are supported; any other drop type returns 400. An ERC-1155 self-mint drop uploads each item's metadata when the item is saved or updated.

Only one upload runs per drop at a time. Calling again while one is running returns that upload's id. Poll GET /api/v2/drops/{slug}/metadata/ipfs/{workflow_execution_id} until status is completed or failed.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "OpenSea API",
    "description": "The API for OpenSea",
    "contact": {
      "name": "OpenSea",
      "url": "https://www.opensea.io",
      "email": "contact@opensea.io"
    },
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://api.opensea.io",
      "description": "OpenSea API server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Drops Endpoints",
      "description": "Endpoints for discovering drops, checking mint eligibility, building mint transactions, and creating drops.\n\nCreating an ERC-721 SeaDrop V1 drop, in the usual order:\n\n1. POST /api/v2/drops/deploy with drop_type `seadrop_v1_erc721`, send the transaction, then poll GET /api/v2/drops/deploy/{chain}/{tx_hash}/receipt for the collection slug.\n2. POST /api/v2/drops/{slug} to save the stages, max supply, and payout address as a draft. Allowlists for `signed_presale` stages are uploaded first with POST /api/v2/drops/{slug}/allowlist.\n3. Items: POST /api/v2/drops/{slug}/items/media for upload contexts and upload each file, optionally upload a metadata manifest with POST /api/v2/drops/{slug}/items/manifest, then save them with POST /api/v2/drops/{slug}/items/media/save-batch. Pass one upload_batch_id on every upload request for the set of files, then save that batch by filename.\n4. Optionally, POST /api/v2/drops/{slug}/prereveal-item to set the placeholder that every token shows until the reveal.\n5. POST /api/v2/drops/{slug}/metadata/ipfs, polling GET /api/v2/drops/{slug}/metadata/ipfs/{workflow_execution_id} until it completes. This writes the real item metadata as the draft base URI.\n6. POST /api/v2/drops/{slug}/publish, sending the transaction from the contract owner. The drop goes live once it is mined and indexed.\n7. Minters use POST /api/v2/drops/{slug}/mint.\n\nStep 5 is the reveal. Run before the publish in step 6, the items are revealed as soon as the drop is live. To reveal later, publish without it, then run it and publish again when ready. POST /api/v2/drops/{slug}/unpublish returns a transaction that closes a live drop.\n\nAn ERC-1155 self-mint drop (drop_type `seadrop_v2_erc1155_self_mint`) skips steps 2 to 7. After deploying, get a media_token for each item's file from POST /api/v2/drops/{slug}/items/media and upload the file to the returned context. Each POST /api/v2/drops/{slug}/items with that token then returns a transaction that creates one token and mints its whole supply to the owner, and PUT /api/v2/drops/{slug}/items/{token_id} returns one that updates an existing token's metadata."
    }
  ],
  "paths": {
    "/api/v2/drops/{slug}/metadata/ipfs": {
      "post": {
        "tags": [
          "Drops Endpoints"
        ],
        "summary": "Upload drop metadata to IPFS",
        "description": "Uploads every saved item's media and metadata to IPFS, then saves the resulting folder as the drop's draft base URI. Run it after POST /api/v2/drops/{slug}/items/media/save-batch; the drop needs at least one item. It does not change the contract: call POST /api/v2/drops/{slug}/publish once it completes.\n\nThis is the reveal. The base URI it writes points at the real item metadata, so a drop published after it has completed is revealed as soon as it is live. To reveal later, publish without running it (showing the prereveal item from POST /api/v2/drops/{slug}/prereveal-item), then run it and publish again when ready.\n\nOnly ERC-721 SeaDrop V1 drops are supported; any other drop type returns 400. An ERC-1155 self-mint drop uploads each item's metadata when the item is saved or updated.\n\nOnly one upload runs per drop at a time. Calling again while one is running returns that upload's id. Poll GET /api/v2/drops/{slug}/metadata/ipfs/{workflow_execution_id} until status is completed or failed.",
        "operationId": "upload_drop_metadata_to_ipfs",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "description": "Collection slug",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "cool-cats"
          }
        ],
        "responses": {
          "200": {
            "description": "Upload started, or the upload already running for this drop",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/DropMetadataUploadResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Conflict",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/V1ErrorWrapper"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "security": [
          {
            "ApiKeyAuth": [],
            "WalletAuth": [
              "write:drops"
            ]
          }
        ],
        "x-opensea-auth-required": true,
        "x-opensea-auth-scopes": [
          "write:drops"
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "V1ErrorWrapper": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code, on the errors that have one. Branch on it rather than on the message text, which may change.",
            "example": "MINTER_NOT_ELIGIBLE"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "errors"
        ]
      },
      "DropMetadataUploadResponse": {
        "type": "object",
        "description": "Started upload of a drop's item media and metadata to IPFS",
        "properties": {
          "workflow_execution_id": {
            "type": "string",
            "description": "Opaque id of the upload. Pass it to GET /api/v2/drops/{slug}/metadata/ipfs/{workflow_execution_id} to follow progress."
          }
        },
        "required": [
          "workflow_execution_id"
        ]
      }
    },
    "responses": {
      "BadRequest": {
        "description": "For error reasons, review the response data.",
        "content": {
          "*/*": {
            "schema": {
              "$ref": "#/components/schemas/V1ErrorWrapper"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Invalid or missing API key"
      },
      "Forbidden": {
        "description": "Wallet token lacks permission for this request",
        "content": {
          "*/*": {
            "schema": {
              "$ref": "#/components/schemas/V1ErrorWrapper"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "*/*": {
            "schema": {
              "$ref": "#/components/schemas/V1ErrorWrapper"
            }
          }
        }
      },
      "InternalError": {
        "description": "Internal server error. Please open a support ticket so OpenSea can investigate."
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "description": "API key required for authentication",
        "name": "x-api-key",
        "in": "header"
      },
      "WalletAuth": {
        "type": "openIdConnect",
        "description": "OpenSea wallet authorization. Run `opensea login` or use the OAuth 2.1 authorization-code flow with PKCE, then send the access token as `Authorization: Bearer <token>`.",
        "openIdConnectUrl": "https://auth.opensea.io/.well-known/openid-configuration"
      }
    }
  },
  "x-tagGroups": [
    {
      "name": "Data & Discovery",
      "tags": [
        "Chain Endpoints",
        "Account Endpoints",
        "Collection Endpoints",
        "NFT Endpoints",
        "Contract Endpoints",
        "Token Endpoints",
        "Search Endpoints",
        "Signal Endpoints"
      ]
    },
    {
      "name": "Marketplace & Trading",
      "tags": [
        "Listing Endpoints",
        "Offer Endpoints",
        "Order Endpoints",
        "Swap Endpoints",
        "Drops Endpoints"
      ]
    },
    {
      "name": "Analytics & Events",
      "tags": [
        "Analytics Endpoints"
      ]
    },
    {
      "name": "Tools [Beta]",
      "tags": [
        "Tool Endpoints [Beta]"
      ]
    },
    {
      "name": "Transactions",
      "tags": [
        "Transaction Endpoints"
      ]
    },
    {
      "name": "Authentication",
      "tags": [
        "Auth Endpoints"
      ]
    }
  ]
}
```