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