Changelog

POAP Moments - MVP

This product is in development and is not intended to be used in a production environment.

Suggest Edits

Note: The current version of this API is open to all users. However, we are in the process of implementing an authentication system that will require client credentials for write operations. As a result, to upload new Moments in the near future, it will be necessary for you to request and obtain your own set of credentials. Please bear this in mind as you continue to use our services.

Entities

Moment

{
    "id": "426b54f8-4460-4917-9c85-64588dcf0c96",
    "author": "0x7CE5368171cC3D988157d7dab3D313d7bd43de3e",
    "createdOn": "2023-04-13T23:10:13.060Z",
    "dropId": 10000,
    "media": {
        "key": "2ab2e87c-fc11-436f-bb44-102f3b746dd2",
        "mimeType": "image/png",
        "status": "PROCESSED",
        "gateways": [
            "https://registry-media-production.s3.us-east-2.amazonaws.com/2ab2e87c-fc11-436f-bb44-102f3b746dd2"
        ],
        "hash": "a519802b7a5c796e083b1452ca0ca855f4746a9c1aaf27780ff8e34b58904000",
        "location": "poap://a519802b7a5c796e083b1452ca0ca855f4746a9c1aaf27780ff8e34b58904000"
    }
}
  • media: An object containing information about the media content associated with the Moment, such as the following:
    • key: A unique identifier for the media file.
    • mimeType: The MIME type of the media file, indicating its format (e.g., "image/png" for a PNG image).
    • status: The processing status of the media file, indicating whether it has been successfully processed or is still pending. Possible values are IN_PROCESS, PROCESSED or FAILED.
    • gateways: A list of URLs where the media file can be accessed and downloaded.
    • hash: A unique hash value representing the media file's content, generated using a SHA-256. This helps ensure the file's integrity and authenticity.
    • location: A custom protocol URL ("poap://...") that points to the media file's location.
  • id: A unique identifier (UUID) for the Moment, used to distinguish it from other Moments.
  • author: The Ethereum account address of the Moment's creator.
  • createdOn: The timestamp indicating when the Moment was created, in ISO 8601 format.
  • dropId: The identifier of the Drop to which the Moment is associated.

Uploading a Moment

This guide provides a step-by-step process for uploading new Moments using any programming language or platform. The steps are focused on the required API endpoints and the data needed for each request.

Steps

  1. Get a signed URL for media upload: Make a POST request to the /moments/media-upload-url endpoint to retrieve a signed URL for uploading the media file.

    curl -X POST "https://moments.poap.tech/moments/media-upload-url"

    The response will contain the signed URL and the media key:

    {
  "url": "<SIGNED_URL>",
  "key": "<MEDIA_KEY>"
}

  2. Upload the media file: Use the signed URL from the previous step to upload the media file. Make a PUT request to the signed URL with the selected media file as the request body and set the Content-Type header to the media file's MIME type.

    curl -X PUT -H "Content-Type: <FILE_MIME_TYPE>" --upload-file <FILE_PATH> "<SIGNED_URL>"

    The request should return a 200 status code if the media file is uploaded successfully.

    Replace <SIGNED_URL> with the URL received in the previous step and <FILE_PATH> with the path to the media file on your system.

  3. Wait for media processing: Poll the /media/<MEDIA_KEY> endpoint to check the media processing status. Keep polling until the response is 200 AND the status is PROCESSED.

    curl -X GET "https://moments.poap.tech/media/<MEDIA_KEY>"

    The response will contain the media's processing status:

    {
  "status": "<PROCESSING_STATUS>"
}

    If you receive an INVALID status, please check that the specified mime-type is correct.

    ⏱️ Wait for a reasonable amount of time (e.g., 2 seconds) between polling attempts. The process takes around 10s for 100MB media files.

  4. Create a Moment: Once the media is processed, create a Moment by making a POST request to the /moments endpoint with the required metadata.

    curl -X POST -H "Content-Type: application/json" -d '{
    "dropId": <DROP_ID>,
    "author": "<ETH_ACCOUNT>",
    "mediaKey": "<MEDIA_KEY>",
}' "https://moments.poap.tech/moments"

    Remember to replace the placeholders (<SIGNED_URL>, <FILE_PATH>, <MEDIA_KEY>, <DROP_ID>, and <ETH_ACCOUNT>) with the appropriate values before executing the curlcommands.

    The request body should contain the following metadata:

    {
  "dropId": <DROP_ID>,
  "author": "<ETH_ACCOUNT>",
  "mediaKey": "<MEDIA_KEY>",
}
    • dropId: The identifier of the POAP Drop associated with the Moment.
    • author: The Ethereum account address of the Moment's creator.
    • mediaKey: The media key obtained in step 1.

    If the request is successful, the Moment will be created, and a success message can be displayed to the user. If there's an error, handle it accordingly and inform the user.

    Retrieve Moments

    Get a Moment by MOMENT_ID

    To retrieve a specific Moment by its MOMENT_ID, make a GET request to the /moments/<MOMENT_ID> endpoint.

    curl -X GET "https://moments.poap.tech/moments/<MOMENT_ID>"

    Replace <MOMENT_ID> with the actual Moment ID. The response will contain the Moment's details.

    Get Moments by DROP_ID

    To retrieve Moments by their DROP_ID, make a GET request to the /moments endpoint with the drop_id, limit, and offset query parameters.

    curl -X GET "https://moments.poap.tech/moments?drop_id=<DROP_ID>&limit=<LIMIT>&offset=<OFFSET>"

    Replace <DROP_ID>, <LIMIT>, and <OFFSET> with the appropriate values. The response will contain a list of Moments associated with the specified Drop ID, along with pagination information.

    • DROP_ID: The identifier of the POAP Drop you want to search for.
    • LIMIT: The maximum number of Moments to return per request (page size). The default value is 10.
    • OFFSET: The starting index for the list of Moments to return (page offset). The default value is 0.

    Remember to replace the placeholders (<MOMENT_ID>, <DROP_ID>, <LIMIT>, and <OFFSET>) with the appropriate values before executing the curl commands.

Updated 4 months ago