tendril/docs/GITEA/Gitea-API-Reference.md

# Gitea API Reference for LLMs

**Purpose**: API differences and considerations when working with Gitea programmatically.

**Reference**: [Gitea API Documentation](https://docs.gitea.com/api/)

---

## Overview

Gitea provides a REST API that is **similar to GitHub's API** but not identical. The API allows programmatic access to repositories, issues, pull requests, and more.

**Base URL**: `https://your-gitea-instance.com/api/v1`

---

## Authentication

### Personal Access Token

**Creating a token**:
1. Log in to Gitea
2. Go to Settings → Applications → Generate New Token
3. Set name and permissions
4. Copy token

**Using token**:
```bash
curl -H "Authorization: token YOUR_TOKEN" \
  https://git.parkingmeter.info/api/v1/user
```

**In code**:
```rust
let client = reqwest::Client::new();
let response = client
    .get("https://git.parkingmeter.info/api/v1/user")
    .header("Authorization", format!("token {}", token))
    .send()
    .await?;
```

---

## Common Endpoints

### User Information

**Get authenticated user**:
```
GET /api/v1/user
```

**Get user by username**:
```
GET /api/v1/users/{username}
```

### Repositories

**List repositories**:
```
GET /api/v1/user/repos
GET /api/v1/users/{username}/repos
GET /api/v1/orgs/{org}/repos
```

**Get repository**:
```
GET /api/v1/repos/{owner}/{repo}
```

**Create repository**:
```
POST /api/v1/user/repos
```

### Issues

**List issues**:
```
GET /api/v1/repos/{owner}/{repo}/issues
```

**Get issue**:
```
GET /api/v1/repos/{owner}/{repo}/issues/{index}
```

**Create issue**:
```
POST /api/v1/repos/{owner}/{repo}/issues
```

### Pull Requests

**List pull requests**:
```
GET /api/v1/repos/{owner}/{repo}/pulls
```

**Get pull request**:
```
GET /api/v1/repos/{owner}/{repo}/pulls/{index}
```

**Create pull request**:
```
POST /api/v1/repos/{owner}/{repo}/pulls
```

---

## Differences from GitHub API

### 1. Base URL

- **GitHub**: `https://api.github.com`
- **Gitea**: `https://your-instance.com/api/v1`

### 2. Issue/PR Numbers

- **GitHub**: Uses sequential numbers across repository
- **Gitea**: Uses index (similar, but may differ in some cases)

### 3. Some Endpoints

- Gitea may have different endpoints for some operations
- Check Gitea API documentation for specific endpoints
- Most common operations are similar

### 4. Webhooks

- Gitea webhooks are compatible with GitHub format
- Same payload structure
- Same event types (push, pull_request, etc.)

---

## For LLMs: API Usage Guidelines

### When Documenting API Usage

**Reference Gitea API**:
```markdown
## API Integration

This project uses the **Gitea API** for programmatic access.

**Base URL**: `https://git.parkingmeter.info/api/v1`

**Authentication**: Personal Access Token

**Example**:
```bash
curl -H "Authorization: token YOUR_TOKEN" \
  https://git.parkingmeter.info/api/v1/user/repos
```
```

### When Creating API Clients

**Use Gitea base URL**:
```rust
const GITEA_BASE_URL: &str = "https://git.parkingmeter.info/api/v1";
```

**Use Gitea authentication**:
```rust
let client = reqwest::Client::new();
let response = client
    .get(&format!("{}/user", GITEA_BASE_URL))
    .header("Authorization", format!("token {}", token))
    .send()
    .await?;
```

### When Referencing Documentation

**Link to Gitea API docs**:
```markdown
For complete API documentation, see:
https://docs.gitea.com/api/
```

---

## Common Use Cases

### 1. Listing Repositories

```bash
curl -H "Authorization: token YOUR_TOKEN" \
  https://git.parkingmeter.info/api/v1/user/repos
```

### 2. Creating an Issue

```bash
curl -X POST \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"New Issue","body":"Issue description"}' \
  https://git.parkingmeter.info/api/v1/repos/owner/repo/issues
```

### 3. Creating a Pull Request

```bash
curl -X POST \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"PR Title","head":"feature-branch","base":"main"}' \
  https://git.parkingmeter.info/api/v1/repos/owner/repo/pulls
```

---

## MCP Server Integration

**Tendril** uses the Gitea MCP server for integration with Zed IDE. The MCP server provides:

- Repository management
- Issue management
- Pull request management
- File operations
- And more

**Reference**: See `src/mcp_server_gitea.rs` for implementation details.

---

## References

- **Gitea API Docs**: https://docs.gitea.com/api/
- **API Overview**: https://docs.gitea.com/api/overview/
- **Authentication**: https://docs.gitea.com/api/authentication/

---

**Location**: `docs/GITEA/Gitea-API-Reference.md`  
**Last Updated**: 2025-01-27