Initial commit
This commit is contained in:
Zhongwei Li
293
skills/agent-smith/references/pocketsmith-api.md
Normal file
293
skills/agent-smith/references/pocketsmith-api.md
Normal file
@@ -0,0 +1,293 @@
|
||||
# PocketSmith API Documentation (Offline Reference)
|
||||
|
||||
**API Version:** v2.0
|
||||
**Base URL:** `https://api.pocketsmith.com/v2`
|
||||
**Documentation Source:** https://developers.pocketsmith.com/
|
||||
**Last Updated:** 2025-11-16
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Introduction](#introduction)
|
||||
2. [Authentication](#authentication)
|
||||
- [Developer Keys](#developer-keys-personal-tools)
|
||||
- [OAuth 2.0](#oauth-20-multi-user-apps)
|
||||
3. [API Reference](#api-reference)
|
||||
- [Users](#users)
|
||||
- [Institutions](#institutions)
|
||||
- [Accounts](#accounts)
|
||||
- [Transaction Accounts](#transaction-accounts)
|
||||
- [Transactions](#transactions)
|
||||
- [Categories](#categories)
|
||||
- [Budgeting](#budgeting)
|
||||
- [Supporting Resources](#supporting-resources)
|
||||
4. [Common Topics](#common-topics)
|
||||
- [Pagination](#pagination)
|
||||
- [Error Handling](#error-handling)
|
||||
5. [Changelog](#changelog)
|
||||
6. [Support](#support)
|
||||
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
The PocketSmith API is freely available to all developers without restrictions. The platform welcomes developers to build tools and integrations using their services.
|
||||
|
||||
**Developer Hub:** https://developers.pocketsmith.com/
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
PocketSmith provides two authentication methods depending on your use case.
|
||||
|
||||
### Developer Keys (Personal Tools)
|
||||
|
||||
For building personal tools like dashboard widgets or transaction importers, use developer keys.
|
||||
|
||||
**Configuration:**
|
||||
- Manage keys in: Settings > Security within your PocketSmith account
|
||||
- **Header:** `X-Developer-Key`
|
||||
- **Access:** Persistent API access to your own account
|
||||
|
||||
**Example Request:**
|
||||
```bash
|
||||
curl --header "X-Developer-Key: YOUR_KEY_HERE" \
|
||||
https://api.pocketsmith.com/v2/me
|
||||
```
|
||||
|
||||
**Supported Languages:**
|
||||
- Shell (curl)
|
||||
- Node.js
|
||||
- JavaScript
|
||||
- PHP
|
||||
- Python
|
||||
|
||||
### OAuth 2.0 (Multi-User Apps)
|
||||
|
||||
To create applications that other PocketSmith users can access, you'll need to use OAuth 2.0.
|
||||
|
||||
**Setup Process:**
|
||||
|
||||
1. **Register your application** by contacting the team at [email protected]
|
||||
2. **Provide details** about yourself and your planned integration
|
||||
3. **Receive credentials:** `client_id` and `client_secret` upon approval
|
||||
4. **Implement authentication** using the OAuth integration guide
|
||||
|
||||
**OAuth Flow:**
|
||||
- Standard OAuth 2.0 authorization code flow
|
||||
- Detailed integration instructions available in the OAuth documentation section
|
||||
|
||||
---
|
||||
|
||||
## API Reference
|
||||
|
||||
The PocketSmith API v2.0 is organized around the following resource categories:
|
||||
|
||||
### Users
|
||||
|
||||
**Endpoints:**
|
||||
- Get authorised user
|
||||
- Get user by ID
|
||||
- Update user information
|
||||
|
||||
**Example - Get the Authorised User:**
|
||||
```
|
||||
GET https://api.pocketsmith.com/v2/me
|
||||
```
|
||||
|
||||
**Purpose:** Gets the user that corresponds to the access token used in the request.
|
||||
|
||||
**Authentication Required:** Yes (Header-based credentials)
|
||||
|
||||
---
|
||||
|
||||
### Institutions
|
||||
|
||||
Manage financial institutions connected to user accounts.
|
||||
|
||||
**Operations:**
|
||||
- Create institution
|
||||
- Read institution details
|
||||
- Update institution information
|
||||
- Delete institution
|
||||
- List all institutions within a user account
|
||||
|
||||
---
|
||||
|
||||
### Accounts
|
||||
|
||||
Complete account management functionality.
|
||||
|
||||
**Operations:**
|
||||
- Get account details
|
||||
- Update account information
|
||||
- Delete account
|
||||
- Create new account
|
||||
- Manage account ordering within users
|
||||
- List accounts by institution
|
||||
|
||||
---
|
||||
|
||||
### Transaction Accounts
|
||||
|
||||
Transaction accounts are the specific accounts where transactions are recorded.
|
||||
|
||||
**Operations:**
|
||||
- Get transaction account details
|
||||
- Update transaction account
|
||||
- List transaction accounts by user
|
||||
|
||||
---
|
||||
|
||||
### Transactions
|
||||
|
||||
Complete transaction lifecycle management with multi-context querying.
|
||||
|
||||
**Query Contexts:**
|
||||
- By user
|
||||
- By account
|
||||
- By category
|
||||
- By transaction account
|
||||
|
||||
**Operations:**
|
||||
- Create transactions within transaction accounts
|
||||
- Read transaction details
|
||||
- Update transactions
|
||||
- Delete transactions
|
||||
- Query and filter transactions
|
||||
|
||||
---
|
||||
|
||||
### Categories
|
||||
|
||||
Manage and organize transaction categories.
|
||||
|
||||
**Operations:**
|
||||
- Category management and organization
|
||||
- List user-specific categories
|
||||
- Create category rules
|
||||
- Update categories
|
||||
- Delete categories
|
||||
|
||||
---
|
||||
|
||||
### Budgeting
|
||||
|
||||
Budget management and analysis features.
|
||||
|
||||
**Features:**
|
||||
- Budget retrieval and summaries
|
||||
- Trend analysis
|
||||
- Forecast cache management
|
||||
|
||||
---
|
||||
|
||||
### Supporting Resources
|
||||
|
||||
Additional resources for comprehensive financial data management:
|
||||
|
||||
- **Events** - Manage financial events
|
||||
- **Attachments** - Attach files to transactions
|
||||
- **Labels** - Label and tag transactions
|
||||
- **Saved Searches** - Save frequently used search queries
|
||||
- **Currencies** - Handle multi-currency support
|
||||
- **Time Zones** - Manage timezone settings
|
||||
|
||||
---
|
||||
|
||||
## Common Topics
|
||||
|
||||
### Pagination
|
||||
|
||||
The API uses pagination for endpoints that return multiple records.
|
||||
|
||||
**Implementation Details:**
|
||||
- Refer to the pagination documentation section for page size limits and navigation
|
||||
- Response headers typically include pagination metadata
|
||||
|
||||
### Error Handling
|
||||
|
||||
The API returns standard HTTP status codes.
|
||||
|
||||
**Common Status Codes:**
|
||||
- `200 OK` - Successful request
|
||||
- `400 Bad Request` - Invalid request parameters
|
||||
- `401 Unauthorized` - Authentication failure
|
||||
- `403 Forbidden` - Insufficient permissions
|
||||
- `404 Not Found` - Resource not found
|
||||
- `500 Internal Server Error` - Server error
|
||||
|
||||
**Error Response Format:**
|
||||
Detailed error handling documentation available at: https://developers.pocketsmith.com/docs
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
### v2.0 - Welcome to the new PocketSmith developer hub
|
||||
**Posted:** Almost 7 years ago by Regan McEntyre
|
||||
|
||||
The development team announced an updated documentation portal: "We've given our developer documentation a bit of a spruce up. Come on in and check it out, and let us know what you think!"
|
||||
|
||||
**Current Status:**
|
||||
- API Version 2.0 is the current stable version
|
||||
- Interactive API documentation powered by OpenAPI 3 specification
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
**Contact the Development Team:**
|
||||
- **Email:** [email protected]
|
||||
|
||||
**Resources:**
|
||||
- **Interactive API Reference:** https://developers.pocketsmith.com/reference
|
||||
- **Complete Guides:** https://developers.pocketsmith.com/docs
|
||||
- **Changelog:** https://developers.pocketsmith.com/changelog
|
||||
|
||||
---
|
||||
|
||||
## Quick Start Guide
|
||||
|
||||
1. **For Personal Tools:**
|
||||
```bash
|
||||
# Get your developer key from Settings > Security
|
||||
curl --header "X-Developer-Key: YOUR_KEY_HERE" \
|
||||
https://api.pocketsmith.com/v2/me
|
||||
```
|
||||
|
||||
2. **For Multi-User Applications:**
|
||||
- Email [email protected] to register your app
|
||||
- Implement OAuth 2.0 flow once approved
|
||||
|
||||
3. **Explore the API:**
|
||||
- Start with the `/me` endpoint to verify authentication
|
||||
- Review the resource categories that match your use case
|
||||
- Test endpoints using the interactive reference
|
||||
|
||||
---
|
||||
|
||||
## Additional Notes
|
||||
|
||||
**OpenAPI Specification:**
|
||||
The API documentation is built using OpenAPI 3, which means:
|
||||
- Interactive testing tools available in the web interface
|
||||
- Machine-readable API specifications
|
||||
- Auto-generated client libraries possible
|
||||
|
||||
**Rate Limiting:**
|
||||
Check the full documentation for any rate limiting policies.
|
||||
|
||||
**Best Practices:**
|
||||
- Always handle errors gracefully
|
||||
- Use pagination for large datasets
|
||||
- Cache responses where appropriate
|
||||
- Follow OAuth 2.0 best practices for multi-user apps
|
||||
|
||||
---
|
||||
|
||||
**End of Documentation**
|
||||
|
||||
For the most up-to-date information and interactive API testing, visit: https://developers.pocketsmith.com/
|
||||
Reference in New Issue
Block a user