krz/hutch

  1# Sourcehut API Reference
  2
  3This document provides context and references for working with SourceHut's APIs.
  4
  5## Official Documentation
  6
  7The official SourceHut API documentation can be found at:
  8- **https://man.sr.ht** - Contains links to API reference pages for all *.sr.ht services
  9
 10## Services and Their APIs
 11
 12### git.sr.ht (Git Repositories)
 13- **GraphQL API**: https://git.sr.ht/graphql
 14- **REST API**: https://git.sr.ht/api
 15- **Scope required**: `REPOSITORIES:RO` (read-only), `REPOSITORIES:RW` (read-write)
 16
 17### todo.sr.ht (Ticket Tracking)
 18- **GraphQL API**: https://todo.sr.ht/graphql
 19- **REST API**: https://todo.sr.ht/api
 20- **Scope required**: `TICKETS:RO` (read-only), `TICKETS:RW` (read-write)
 21
 22### hg.sr.ht (Mercurial Repositories)
 23- **GraphQL API**: https://hg.sr.ht/graphql
 24- **REST API**: https://hg.sr.ht/api
 25- **Scope required**: `REPOSITORIES:RO` (read-only), `REPOSITORIES:RW` (read-write)
 26
 27### lists.sr.ht (Mailing Lists)
 28- **GraphQL API**: https://lists.sr.ht/graphql
 29- **REST API**: https://lists.sr.ht/api
 30- **Scope required**: `LISTS:RO` (read-only), `LISTS:RW` (read-write)
 31
 32### builds.sr.ht (CI/CD)
 33- **GraphQL API**: https://builds.sr.ht/graphql
 34- **REST API**: https://builds.sr.ht/api
 35- **Scope required**: `BUILDS:RO` (read-only), `BUILDS:RW` (read-write)
 36
 37### meta.sr.ht (User Accounts)
 38- **GraphQL API**: https://meta.sr.ht/graphql
 39- **REST API**: https://meta.sr.ht/api
 40- **Scope required**: `ACCOUNT:RO` (read-only), `ACCOUNT:RW` (read-write)
 41
 42## Authentication
 43
 44All API requests require a **Personal Access Token** with the appropriate scopes.
 45
 46- **Token creation**: https://meta.sr.ht/oauth2/personal-token
 47- **Token format**: `Bearer <your-token>` in the Authorization header
 48
 49## GraphQL Conventions
 50
 51### Common Types
 52
 53```graphql
 54# Cursor-based pagination
 55type Query {
 56  items(cursor: Cursor, filter: Filter): ItemsPage
 57}
 58
 59type ItemsPage {
 60  results: [Item!]!
 61  cursor: Cursor
 62}
 63
 64# Filter structure (varies by service)
 65input Filter {
 66  search: String
 67  # ... other service-specific filters
 68}
 69```
 70
 71### Error Handling
 72
 73    SourceHut APIs return GraphQL errors in the following format:
 74
 75```json
 76{
 77  "data": null,
 78  "errors": [
 79    {
 80      "message": "Error message",
 81      "path": ["query", "field"],
 82      "extensions": {
 83        "code": "ERROR_CODE"
 84      }
 85    }
 86  ]
 87}
 88```
 89
 90## Rate Limiting
 91
 92- **Rate limits**: Vary by service and authentication status
 93- **Headers**: Check `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
 94- **Unauthenticated**: Lower limits (typically 60 requests/hour)
 95- **Authenticated**: Higher limits (typically 5000 requests/hour)
 96
 97## Development Notes
 98
 99### API Exploration
100
101Use GraphiQL interfaces available at each service's `/graphql` endpoint to:
102- Explore the schema
103- Test queries
104- Understand available fields and types
105
106### Common Issues
107
1081. **Filtering**: Some services may not support all filter operations. Check the schema.
1092. **Pagination**: Always handle `cursor` properly for pagination.
1103. **Caching**: SourceHut APIs may have aggressive caching. Use cache headers appropriately.
111
112### Example Query Structure
113
114```graphql
115query {
116  repositories(cursor: $cursor, filter: $filter) {
117    results {
118      id
119      name
120      description
121      # ... other fields
122    }
123    cursor
124  }
125}
126
127# Variables
128{
129  "filter": {
130    "search": "query string"
131  }
132}
133```
134
135## Troubleshooting
136
1371. **401 Unauthorized**: Check token scopes and expiration
1382. **403 Forbidden**: Verify you have access to the requested resource
1393. **429 Too Many Requests**: Implement proper rate limiting in your client
1404. **500 Internal Server Error**: Check if the API is temporarily down
141
142## Additional Resources
143
144- SourceHut API Status: https://status.sr.ht
145- SourceHut Man Pages: https://man.sr.ht
146- IRC: #sr.ht on Libera.Chat