{"id":28564261,"url":"https://github.com/checkernetwork/spark-api","last_synced_at":"2025-10-25T11:34:33.784Z","repository":{"id":165914163,"uuid":"641322851","full_name":"CheckerNetwork/spark-api","owner":"CheckerNetwork","description":"💥 SPARK API","archived":false,"fork":false,"pushed_at":"2025-06-10T10:38:35.000Z","size":2920,"stargazers_count":3,"open_issues_count":16,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-06-10T11:24:23.248Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/filecoin-station/spark","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CheckerNetwork.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-05-16T08:32:24.000Z","updated_at":"2025-06-10T10:36:36.000Z","dependencies_parsed_at":"2023-09-23T09:57:53.882Z","dependency_job_id":"6c856a5c-6c27-4d59-97e1-1078858dd206","html_url":"https://github.com/CheckerNetwork/spark-api","commit_stats":null,"previous_names":["checkernetwork/spark-api","filecoin-station/spark-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CheckerNetwork%2Fspark-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CheckerNetwork%2Fspark-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CheckerNetwork%2Fspark-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CheckerNetwork%2Fspark-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CheckerNetwork","download_url":"https://codeload.github.com/CheckerNetwork/spark-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CheckerNetwork%2Fspark-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259085461,"owners_count":22803206,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-10T13:35:44.163Z","updated_at":"2025-10-25T11:34:33.698Z","avatar_url":"https://github.com/CheckerNetwork.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# spark-api\n[SPARK](https://github.com/filecoin-station/spark) API\n\n[![CI](https://github.com/filecoin-station/spark-api/actions/workflows/ci.yml/badge.svg)](https://github.com/filecoin-station/spark-api/actions/workflows/ci.yml)\n\n## Routes\n\n### `POST /retrievals`\n\nStart a new retrieval.\n\nBody:\n\n```typescript\n{\n  sparkVersion: String,\n  zinniaVersion: String\n}\n```\n\nResponse:\n\n```typescript\n{\n  id: String,\n  cid: String,\n  providerAddress: String,\n  protocol: 'graphsync'|'bitswap'|'http'\n}\n```\n\n### `PATCH /retrievals/:id`\n\nParameters:\n- `id`: Request ID (from `POST /retrievals`)\n\nBody:\n\n```typescript\n{\n  participantAddress: String,\n  timeout: Boolean,\n  startAt: String,       // ISO 8601\n  statusCode: Number,\n  firstByteAt: String,   // ISO 8601\n  endAt: String,         // ISO 8601\n  byteLength: Number,\n  attestation: String,\n  stationId: String\n}\n```\n\nDates should be formatted as [ISO 8601](https://tc39.es/ecma262/#sec-date-time-string-format)\nstrings.\n\nResponse:\n\n```\nOK\n```\n\n### `GET /miner/:minerId/deals/eligible/summary`\n\nParameters:\n- `minerId` - a miner id like `f0814049`\n\nResponse:\n\nNumber of deals grouped by client IDs.\n\n```json\n{\n  \"minerId\": \"f0814049\",\n  \"dealCount\": 13878,\n  \"clients\": [\n    { \"clientId\": \"f02516933\", \"dealCount\": 6880 },\n    { \"clientId\": \"f02833886\", \"dealCount\": 3126 }\n  ]\n}\n```\n\n### `GET /client/:clientId/deals/eligible/summary`\n\nParameters:\n- `clientId` - a client id like `f0215074`\n\nResponse:\n\nNumber of deals grouped by miner IDs.\n\n```json\n{\n  \"clientId\": \"f0215074\",\n  \"dealCount\": 38977,\n  \"providers\": [\n    { \"minerId\": \"f01975316\", \"dealCount\": 6810 },\n    { \"minerId\": \"f01975326\", \"dealCount\": 6810 }\n  ]\n}\n```\n\n### `GET /allocator/:allocatorId/deals/eligible/summary`\n\nParameters:\n- `allocatorId` - an allocator id like `f03015751`\n\nResponse:\n\nNumber of deals grouped by client IDs.\n\n```json\n{\n  \"allocatorId\": \"f03015751\",\n  \"dealCount\": 4088,\n  \"clients\": [\n    { \"clientId\": \"f03144229\", \"dealCount\": 2488 },\n    { \"clientId\": \"f03150656\", \"dealCount\": 1600 }\n  ]\n}\n```\n\n## Development\n\n### Database\n\nSet up [PostgreSQL](https://www.postgresql.org/) with default settings:\n - Port: 5432\n - User: _your system user name_\n - Password: _blank_\n - Database: _same as user name_\n\nAlternatively, set the environment variable `$DATABASE_URL` with `postgres://${USER}:${PASS}@${HOST}:${POST}/${DATABASE}`.\n\nThe Postgres user and database need to already exist, and the user\nneeds full management permissions for the database.\n\nYou can also the following command to set up the PostgreSQL server via Docker:\n\n```bash\ndocker run -d --name spark-db \\\n  -e POSTGRES_HOST_AUTH_METHOD=trust \\\n  -e POSTGRES_USER=$USER \\\n  -e POSTGRES_DB=$USER \\\n  -p 5432:5432 \\\n  postgres\n```\n\nWhen working on multiple Spark-related services, we recommend to use the following commands to create or reset the Postgres instance:\n\n```bash\ndocker rm -f meridian-db \u0026\u0026 docker run --name meridian-db -e POSTGRES_HOST_AUTH_METHOD=trust -e POSTGRES_USER=$USER -e POSTGRES_DB=$USER -p 5432:5432 -d postgres \u0026\u0026 sleep 1; psql postgres://localhost:5432/ -c \"CREATE DATABASE spark_evaluate\" \u0026\u0026 psql postgres://localhost:5432/ -c \"CREATE DATABASE spark_stats\" \u0026\u0026 psql postgres://localhost:5432/ -c \"CREATE DATABASE spark\"\n```\n\n### `api`\n\nStart the API service:\n\n```bash\nnpm start --workspace api\n```\n\nRun tests and linters:\n\n```bash\nnpm test --workspace api\nnpm run lint --workspace api\n```\n\n## Deployment\n\nPushes to `main` will be deployed automatically.\n\nPerform manual devops using [Fly.io](https://fly.io):\n\n```bash\n$ fly deploy api\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheckernetwork%2Fspark-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcheckernetwork%2Fspark-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheckernetwork%2Fspark-api/lists"}