tendril/kb/02_systems/2025-11-11--gitea-api-reference--howto.md

---
title: "Gitea API Reference"
date: "2025-11-11"
captured_at: "2025-11-11"
author: ["datawarrior"]
source: { kind: doc, ref: "docs/GITEA/Gitea-API-Reference.md" }
source_type: personal_note
project: ["tendril"]
related_projects: ["tendril"]
topics: ["gitea", "api", "programming", "integration", "mcp"]
tags: ["gitea", "api", "programming", "integration", "mcp", "rest-api"]
type: howto
status: active
phase_relevance: []
routing_hint: "Gitea API reference guide - infrastructure/tooling documentation"
proposed_path: "kb/02_systems/"
routing_confidence: 0.95
related: ["docs/GITEA/Gitea-API-Reference.md", "src/mcp_server_gitea.rs"]
summary: "API differences and considerations when working with Gitea programmatically. Covers authentication, common endpoints, differences from GitHub API, and MCP server integration for Tendril."
key_takeaways: []
action_candidates: []
---

# Gitea API Reference

## 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`

For Tendril: `https://git.parkingmeter.info/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 example):
```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?;
```

## 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/

---

**Original Location**: `docs/GITEA/Gitea-API-Reference.md`  
**Last Updated**: 2025-01-27  
**Related**: 
- `src/mcp_server_gitea.rs` - MCP server implementation
- `docs/GITEA/Gitea-Basics.md`