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.

Quick Reference: Which Resource Do I Need?

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)

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 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)

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

Common HTTP Patterns

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
• C

...