freeagent-api

name	freeagent-api
description	Interacts with the FreeAgent accounting API to manage invoices, contacts, projects, expenses, timeslips, and other financial data. Use when the user needs to retrieve, create, update, or analyze FreeAgent accounting information via the API. All write operations (POST/PUT/DELETE) require explicit user confirmation before execution and default to sandbox unless production is explicitly requested.
allowed-tools	Bash, Read, Write, Edit, WebFetch
version	2

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

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

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.