Skip to content

api-reference.md

Latest commit

 

History

History
420 lines (335 loc) · 8.75 KB

api-reference.md

File metadata and controls

420 lines (335 loc) · 8.75 KB
Raw
id api-reference
title Astral API Reference
sidebar_label API Reference
slug /api-reference

Astral API Reference

The Astral Protocol API provides access to location proof attestations from multiple blockchains. This document covers all available endpoints, request parameters, and response formats.

Base URL

The base URL for all API endpoints is:

https://api.astral.global

Authentication

The API currently does not require authentication for read operations. Future versions may implement authentication for permissioned read and write operations.

Content Type

All requests and responses use JSON format. Include the following header in your requests:

Content-Type: application/json

Endpoints

Health Check

GET /health

Checks if the API is running.

Response

{
  "status": "ok",
  "message": "Astral API is running"
}

API Root

GET /

Returns basic information about the API and available endpoints.

Response

{
  "title": "Astral Protocol Location Proof API",
  "description": "API for querying location proof attestations across multiple blockchains",
  "version": "v0",
  "links": [
    {
      "rel": "self",
      "href": "/",
      "type": "application/json"
    },
    {
      "rel": "api",
      "href": "/api/v0",
      "type": "application/json"
    },
    {
      "rel": "config",
      "href": "/api/v0/config",
      "type": "application/json"
    },
    {
      "rel": "sync",
      "href": "/api/sync",
      "type": "application/json"
    },
    {
      "rel": "location-proofs",
      "href": "/api/v0/location-proofs",
      "type": "application/json"
    }
  ]
}

Get Configuration

GET /api/v0/config

Returns the API configuration including supported chains and EAS schema information.

Response

{
  "chains": {
    "arbitrum": true,
    "celo": true,
    "sepolia": true,
    "base": true
  },
  "schema": "0xba4171c92572b1e4f241d044c32cdf083be9fd946b8766977558ca6378c824e2",
  "schema_fields": "uint256 eventTimestamp,string srs,string locationType,string location,string[] recipeType,bytes[] recipePayload,string[] mediaType,string[] mediaData,string memo",
  "version": "v0"
}

Get Location Proofs

GET /api/v0/location-proofs

Returns a list of location proofs based on the provided query parameters.

Query Parameters

Parameter Type Description
chain string Filter by blockchain (arbitrum, celo, sepolia, base)
prover string Filter by the address that created the proof
subject string Filter by the subject address
fromTimestamp ISO date string Filter proofs after this timestamp
toTimestamp ISO date string Filter proofs before this timestamp
bbox array Bounding box in format [minLng, minLat, maxLng, maxLat]
limit number Maximum number of results to return (default: 100)
offset number Pagination offset

Response

{
  "data": [
    {
      "uid": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "chain": "sepolia",
      "prover": "0xabcdef1234567890abcdef1234567890abcdef12",
      "subject": "0xabcdef1234567890abcdef1234567890abcdef12",
      "timestamp": "2023-09-15T12:34:56Z",
      "event_timestamp": "2023-09-15T12:34:56Z",
      "srs": "WGS84",
      "location_type": "point",
      "location": "{\"type\":\"Point\",\"coordinates\":[-122.4194,37.7749]}",
      "longitude": -122.4194,
      "latitude": 37.7749,
      "recipe_types": ["gps", "ip"],
      "recipe_payloads": ["...", "..."],
      "media_types": ["image/jpeg"],
      "media_data": ["..."],
      "memo": "San Francisco city center",
      "revoked": false,
      "created_at": "2023-09-15T12:35:00Z",
      "updated_at": "2023-09-15T12:35:00Z"
    }
    // ... more location proofs
  ],
  "count": 1,
  "limit": 100,
  "offset": 0
}

Get Location Proof by UID

GET /api/v0/location-proofs/:uid

Returns a specific location proof by its unique identifier (UID).

Parameters

Parameter Type Description
uid string The unique identifier of the location proof

Response

{
  "uid": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "chain": "sepolia",
  "prover": "0xabcdef1234567890abcdef1234567890abcdef12",
  "subject": "0xabcdef1234567890abcdef1234567890abcdef12",
  "timestamp": "2023-09-15T12:34:56Z",
  "event_timestamp": "2023-09-15T12:34:56Z",
  "srs": "WGS84",
  "location_type": "point",
  "location": "{\"type\":\"Point\",\"coordinates\":[-122.4194,37.7749]}",
  "longitude": -122.4194,
  "latitude": 37.7749,
  "recipe_types": ["gps", "ip"],
  "recipe_payloads": ["...", "..."],
  "media_types": ["image/jpeg"],
  "media_data": ["..."],
  "memo": "San Francisco city center",
  "revoked": false,
  "created_at": "2023-09-15T12:35:00Z",
  "updated_at": "2023-09-15T12:35:00Z"
}

Get Location Proofs Statistics

GET /api/v0/location-proofs/stats

Returns statistics about location proofs in the database.

Response

{
  "total": 1250,
  "by_chain": {
    "arbitrum": 320,
    "celo": 180,
    "sepolia": 450,
    "base": 300
  },
  "by_time": {
    "last_24_hours": 50,
    "last_7_days": 210,
    "last_30_days": 480
  },
  "revoked": 15
}

Trigger Sync

POST /api/sync

Triggers a synchronization of attestations from EAS for all chains or a specific chain.

Query Parameters

Parameter Type Description
chain string Optional. Sync only a specific chain (arbitrum, celo, sepolia, base)

Response (All Chains)

{
  "status": "success",
  "message": "Full sync cycle started"
}

Response (Specific Chain)

{
  "status": "success",
  "message": "Successfully synced 25 attestations from sepolia",
  "chain": "sepolia",
  "count": 25
}

Get Sync Status

GET /api/sync/status

Returns the current status of the synchronization process.

Response

{
  "status": "ok",
  "worker": {
    "running": true,
    "isAttestationSyncRunning": false,
    "isRevocationCheckRunning": false,
    "startTime": "2023-09-15T10:00:00Z",
    "uptime": 7200,
    "lastSuccessfulRun": "2023-09-15T12:00:00Z",
    "lastRunDuration": "25.30s",
    "totalRuns": 12,
    "successfulRuns": 11,
    "failedRuns": 1
  },
  "attestations": {
    "totalIngested": 1250,
    "byChain": {
      "arbitrum": 320,
      "celo": 180,
      "sepolia": 450,
      "base": 300
    },
    "lastRunIngested": {
      "arbitrum": 5,
      "celo": 2,
      "sepolia": 8,
      "base": 10
    }
  },
  "revocationChecks": {
    "lastRun": "2023-09-15T11:30:00Z",
    "totalChecked": 1000,
    "totalRevoked": 15
  },
  "supportedChains": ["arbitrum", "base", "celo", "sepolia"],
  "recentErrors": [
    {
      "timestamp": "2023-09-15T11:15:00Z",
      "message": "Network timeout for GraphQL request",
      "chain": "arbitrum"
    }
  ]
}

Trigger Revocation Check

POST /api/sync/revocations

Triggers a check for revocations of existing attestations.

Response

{
  "status": "success",
  "message": "Revocation check started"
}

Control Worker

POST /api/sync/worker

Controls the background worker that performs synchronization.

Query Parameters

Parameter Type Description
action string The action to perform (start or stop)

Response (Start)

{
  "status": "success",
  "message": "Background worker started"
}

Response (Stop)

{
  "status": "success",
  "message": "Background worker stopped"
}

Error Responses

All API endpoints return appropriate HTTP status codes and error messages in case of failures.

Example Error Response

{
  "status": "error",
  "message": "Failed to get sync status",
  "error": "Database connection error"
}

Common Status Codes

Status Code Description
200 OK - The request was successful
202 Accepted - The request has been accepted for processing
400 Bad Request - The request was invalid
404 Not Found - The requested resource was not found
409 Conflict - The request couldn't be processed due to a conflict
500 Internal Server Error - Something went wrong on the server

Rate Limiting

The API currently does not implement rate limiting, but users should be mindful of their request frequency to ensure optimal performance for all users.

Pagination

The API supports pagination through the limit and offset parameters for endpoints that return collections.

Example:

GET /api/v0/location-proofs?limit=20&offset=40

This will return 20 location proofs starting from the 41st record.