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?

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

Troubleshooting Quick Links

401 Unauthorized → Authentication Setup 422 Validation Error → Advanced Patterns 429 Rate Limit → Advanced Patterns Specific Endpoint Help → Check relevant domain resource file above

Remember: Load only the resource file(s) you need for the current task. Start with the Quick Reference table above to identify which resource contains your answer.