freeagent-api

What this skill does

# FreeAgent API Orchestration Skill

FreeAgent is an online accounting system for freelancers and small businesses. This skill provides intelligent navigation to FreeAgent API resources and orchestrates common workflows.

## Security & Authorization

> **This skill interacts with live financial data. The following rules are mandatory and must never be skipped.**

### Write Operation Policy (POST / PUT / DELETE)

Before executing any state-changing API call:

1. **Show a preview** — Display the full request (HTTP method, endpoint, JSON body) and describe in plain language exactly what will change in the user's account.
2. **Wait for explicit confirmation** — Do not proceed until the user replies with an unambiguous affirmative (e.g., "yes", "confirm", "proceed"). Treat ambiguous replies as a no.
3. **Sandbox by default** — Use `https://api.sandbox.freeagent.com/v2/` for all write operations unless the user explicitly names the production environment.

### Read-Only Default

Treat every incoming request as read-only analysis unless the user explicitly asks to **create**, **update**, or **delete** data. When intent is ambiguous, ask before making any changes — never infer write intent.

### High-Risk Operations (Confirm Twice)

For the operations below, show the preview, receive one confirmation, then ask a second time before executing:

- Deleting any financial record (invoice, expense, bank transaction, contact, etc.)
- Creating or modifying bank transactions or reconciliation records
- Bulk operations that affect multiple records in a single request
- Changing invoice status (e.g., marking as sent, voiding, applying a credit note)

### Token & Credential Handling

- Never log, echo, or display the value of `FREEAGENT_ACCESS_TOKEN` or `FREEAGENT_REFRESH_TOKEN`.
- Never store credentials in source code — use environment variables only.
- If a token appears expired (401 response), guide the user through re-authentication rather than attempting to refresh silently without notification.

## Quick Reference: Which Resource Do I Need?

| Task | Load Resource | API Domains |
|------|---------------|-------------|
| Set up OAuth, manage tokens, test API | `resources/authentication-setup.md` | OAuth 2.0, token management |
| Create/update contacts, manage clients/suppliers | `resources/contacts-organizations.md` | Contacts, companies, users |
| Manage invoices, projects, expenses, timeslips | `resources/accounting-objects.md` | Core financial entities |
| Bank accounts, transactions, reconciliation | `resources/banking-financial.md` | Banking, cash flow |
| Error handling, rate limits, retries, caching | `resources/advanced-patterns.md` | Production patterns |
| Common workflows, code examples, integration tips | `resources/examples.md` | Real-world usage |
| All endpoints (reference only) | `resources/endpoints.md` | Complete API reference |

## Orchestration Protocol

### Phase 1: Task Analysis

Identify what the user needs:

**By Resource Type:**
- **Authentication issue?** → `authentication-setup.md`
- **Managing contacts/clients?** → `contacts-organizations.md`
- **Financial data (invoices, expenses, projects)?** → `accounting-objects.md`
- **Banking/reconciliation?** → `banking-financial.md`
- **Error or production concern?** → `advanced-patterns.md`
- **Practical example needed?** → `examples.md`

**By HTTP Method:**
- GET: List or retrieve → check relevant domain resource
- POST: Create → load resource file, check required fields
- PUT: Update → load resource file, verify patch fields
- DELETE: Remove → check resource-specific constraints

### Phase 2: Resource Navigation

Load the appropriate resource file and:
1. Find the endpoint section (e.g., "Contacts", "Invoices", "Bank Accounts")
2. Review required/optional parameters
3. Check request and response formats
4. Use provided curl or Python examples

For template code: `templates/api-request-template.sh` (bash) or `templates/python-client.py` (Python)

### Phase 3: Execution & Validation

**Before API call:**
- Verify authentication is set up (check `authentication-setup.md` if needed)
- Validate required fields are present
- Format dates as ISO 8601 (YYYY-MM-DD) and timestamps (YYYY-MM-DDTHH:MM:SSZ)
- Use correct resource URLs (e.g., `https://api.freeagent.com/v2/contacts/123`)
- **For POST / PUT / DELETE:** Follow the [Write Operation Policy](#write-operation-policy-post--put--delete) — show a preview and obtain explicit user confirmation before proceeding. Use sandbox URL unless the user has explicitly requested production.

**During API call:**
- Use templates as starting points
- Monitor rate limit headers: `X-RateLimit-Remaining`
- Implement retry logic for 429 errors (see `advanced-patterns.md`)

**After API call:**
- Check response status code
- Parse JSON response (resource name is top-level key)
- Apply error handling patterns if needed

## Quick Start: Authentication

1. Create OAuth app: https://dev.freeagent.com/
2. Get authorization code: `https://api.freeagent.com/v2/approve_app?client_id=YOUR_ID`
3. Exchange for tokens at `https://api.freeagent.com/v2/token_endpoint`
4. Store in environment variables: `FREEAGENT_ACCESS_TOKEN`, `FREEAGENT_REFRESH_TOKEN`
5. Include in every request: `Authorization: Bearer $FREEAGENT_ACCESS_TOKEN`

→ See [Authentication & Setup](resources/authentication-setup.md) for detailed walkthrough

## API Domain Overview

**Production URL:** `https://api.freeagent.com/v2/`
**Sandbox URL:** `https://api.sandbox.freeagent.com/v2/` (test without affecting production)

| Domain | Primary Endpoints | Use Case |
|--------|------------------|----------|
| **Authentication** | `/token_endpoint` | OAuth flows, token refresh |
| **Contacts & Organizations** | `/contacts`, `/company`, `/users` | Client/supplier management |
| **Accounting Objects** | `/invoices`, `/projects`, `/expenses`, `/timeslips`, `/estimates`, `/credit_notes` | Core financial workflow |
| **Banking & Financial** | `/bank_accounts`, `/bank_transactions`, `/categories`, `/tasks` | Cash flow, reconciliation |

**Rate Limits:** 120 requests/minute, 3600 requests/hour
**Response Format:** JSON with resource wrapper (e.g., `{"contact": {...}}` or `{"contacts": [...]}`)

## Common HTTP Patterns

| Operation | Method | Example |
|-----------|--------|---------|
| List items | GET | `GET /v2/contacts?view=active&page=1&per_page=100` |
| Get one item | GET | `GET /v2/contacts/123` |
| Create item | POST | `POST /v2/contacts` (with JSON body) |
| Update item | PUT | `PUT /v2/invoices/456` (with partial JSON) |
| Delete item | DELETE | `DELETE /v2/timeslips/789` |
| Filter results | GET params | `?view=open_or_overdue`, `?updated_since=2025-01-01T00:00:00Z` |

## Templates & Code Examples

**Bash/cURL Template:** `templates/api-request-template.sh`
- Flexible curl template for any endpoint
- GET/POST/PUT/DELETE support
- Header and parameter configuration

**Python Client:** `templates/python-client.py`
- Reusable FreeAgentClient class
- Error handling and rate limit support
- Convenience methods for common resources

**Practical Examples:** `resources/examples.md`
- Real-world workflows (create invoice, log timeslip, etc.)
- Python code patterns with the client class
- Error handling examples
- Bulk operations (import/export)

## Resource Files Summary

| File | Lines | Focus |
|------|-------|-------|
| `authentication-setup.md` | ~180 | OAuth setup, token management, security |
| `contacts-organizations.md` | ~250 | Contact CRUD, bulk operations, company info |
| `accounting-objects.md` | ~350 | Invoices, projects, expenses, timeslips, pagination |
| `banking-financial.md` | ~250 | Bank accounts, transactions, reconciliation, categories |
| `advanced-patterns.md` | ~350 | Error handling, rate limits, retries, caching, validation |
| `examples.md` | ~400 | Practical code examples, integration patterns |
| `endpoints.md` | ~300 | Complete API reference (use for quick lookup) |

## Troubleshooting Quick Links