167 lines
6.3 KiB
Markdown
167 lines
6.3 KiB
Markdown
# Filevine API Curl Skill
|
|
|
|
This skill enables intelligent exploration of the Filevine API by making curl requests and analyzing data patterns.
|
|
|
|
## Capabilities
|
|
|
|
1. **Discover relevant data within a project** - Search across all endpoints used in sync.py
|
|
2. **Make educated guesses** - Use patterns from sample data to infer where data might exist
|
|
3. **Query specific fields** - Search for fields like "matter number", "case number", dates, etc.
|
|
|
|
## API Endpoints Discovered
|
|
|
|
Based on analysis of `sync.py`, the following endpoints are used:
|
|
|
|
| Endpoint | Purpose | Related Code |
|
|
|----------|---------|--------------|
|
|
| `Projects/{id}` | Project details (name, URLs, dates, phase) | `fetch_project_detail()` |
|
|
| `Projects/{id}/team` | Team members and roles | `fetch_project_team()` |
|
|
| `Projects/{id}/tasks` | Project tasks | `fetch_project_tasks()` |
|
|
| `Projects/{id}/Forms/{form}` | Specific forms (datesAndDeadlines, newFileReview, etc.) | `fetch_form()` |
|
|
| `Projects/{id}/Contacts` | Project contacts | `fetch_contacts()` |
|
|
| `Contacts/{id}` | Client information | `fetch_client()` |
|
|
| `Projects/{id}/Collections/{collection}` | Collections (serviceInfo) | `fetch_collection()` |
|
|
|
|
## Sample Data Patterns
|
|
|
|
From examining `examples/*.json`, here are common patterns:
|
|
|
|
**Project-level fields (Projects/{id}):**
|
|
- `projectName` - Full project name
|
|
- `number` - Project number
|
|
- `incidentDate` - Incident date
|
|
- `projectEmailAddress` - Email address
|
|
- `projectUrl` - Link to Filevine
|
|
- `phaseName` - Current phase
|
|
- `createdDate` - Creation date
|
|
|
|
**DatesAndDeadlines form:**
|
|
- `caseNumber` - Case number
|
|
- `dateCaseFiled` - Case filed date
|
|
- `defaultDate` - Default date
|
|
- `trialDate` - Trial date
|
|
- `mSCDate` - MSC date
|
|
- `noticeExpirationDate` - Notice expiration
|
|
- `judgmentDate` - Judgment date
|
|
|
|
**NewFileReview form:**
|
|
- `noticeServiceDate` - When notice was served
|
|
- `noticeExpirationDate` - Notice expiration
|
|
- `noticeType` - Type of notice (NP, PPQ, etc.)
|
|
- `amountDemandedInNotice` - Amount demanded
|
|
|
|
**ComplaintInfo form:**
|
|
- `totalDamagesSought` - Total damages
|
|
- `complaintVerificationBy` - Verification method
|
|
|
|
## Usage
|
|
|
|
When the user asks about finding data, follow this workflow:
|
|
|
|
### 1. Parse the Query
|
|
|
|
Identify what the user wants to find:
|
|
- Field name (e.g., "matter number", "case number", "trial date")
|
|
- Context (e.g., "in a project", "in the datesAndDeadlines form")
|
|
|
|
### 2. Generate Endpoint Candidates
|
|
|
|
Based on the query, suggest multiple endpoints to check:
|
|
|
|
**For case/project identifiers:**
|
|
- `Projects/{id}` (check `number`, `caseNumber` fields)
|
|
- `Projects/{id}/Forms/datesAndDeadlines` (check `caseNumber` field)
|
|
- `Projects/{id}/Forms/matterOverview` (check `matterNumber` field)
|
|
|
|
**For dates:**
|
|
- `Projects/{id}` (check `incidentDate`, `createdDate`)
|
|
- `Projects/{id}/Forms/datesAndDeadlines` (check `trialDate`, `mSCDate`, `defaultDate`, etc.)
|
|
- `Projects/{id}/Forms/newFileReview` (check `noticeServiceDate`)
|
|
|
|
**For contact/defendant info:**
|
|
- `Projects/{id}/Contacts` (check contact list for defendant)
|
|
- `Contacts/{client_id}` (check full contact info)
|
|
|
|
**For attorney/team:**
|
|
- `Projects/{id}/team` (check `teamOrgRoles` for "Assigned Attorney", "Primary", etc.)
|
|
|
|
**For notices:**
|
|
- `Projects/{id}/Forms/newFileReview` (check `noticeType`, `noticeExpirationDate`, etc.)
|
|
- `Projects/{id}/Collections/serviceInfo` (check service dates)
|
|
|
|
### 3. Execute curl Commands
|
|
|
|
For each candidate endpoint, construct and execute curl commands using the auth headers from the codebase:
|
|
|
|
```bash
|
|
curl -X GET "https://api.filevineapp.com/fv-app/v2/Projects/{PROJECT_ID}/{ENDPOINT}" \
|
|
-H "Accept: application/json" \
|
|
-H "Authorization: Bearer {BEARER_TOKEN}" \
|
|
-H "x-fv-orgid: {ORG_ID}" \
|
|
-H "x-fv-userid: {USER_ID}"
|
|
```
|
|
|
|
Use the project ID from sample data (e.g., `15974631` or `15914808`) as a placeholder.
|
|
|
|
### 4. Analyze Results
|
|
|
|
Look for the queried field in the JSON response:
|
|
- Search field names (not values)
|
|
- Check nested objects and arrays
|
|
- Note which endpoints actually contain the data
|
|
|
|
### 5. Report Findings
|
|
|
|
Provide:
|
|
1. The field value(s) found
|
|
2. The endpoint(s) that contain it
|
|
3. Any related fields discovered in the same endpoint
|
|
4. Context about how this data is used in the application
|
|
|
|
## Common Patterns to Guess From
|
|
|
|
When the user asks "What endpoint should I hit to find [field]?", consider:
|
|
|
|
**Field Mapping:**
|
|
| Common Field Names | Likely Endpoints |
|
|
|-------------------|------------------|
|
|
| `matterNumber`, `matter number` | `Projects/{id}/Forms/matterOverview` |
|
|
| `caseNumber`, `case number` | `Projects/{id}/Forms/datesAndDeadlines` |
|
|
| `incident date`, `incidentDate` | `Projects/{id}`, `Projects/{id}/Forms/datesAndDeadlines` |
|
|
| `trial date`, `trialDate` | `Projects/{id}/Forms/datesAndDeadlines` |
|
|
| `notice service date`, `noticeServiceDate` | `Projects/{id}/Forms/newFileReview` |
|
|
| `notice expiration date`, `noticeExpirationDate` | `Projects/{id}/Forms/newFileReview` |
|
|
| `notice type` | `Projects/{id}/Forms/newFileReview` |
|
|
| `assigned attorney` | `Projects/{id}/team` (role: "Assigned Attorney") |
|
|
| `primary contact`, `staff person` | `Projects/{id}/team` (role: "Primary") |
|
|
| `defendant` | `Projects/{id}/Contacts` (filter for "Defendant" role) |
|
|
| `client` | `Contacts/{client_id}` or `Projects/{id}` (clientId field) |
|
|
|
|
## Environment Setup
|
|
|
|
When executing curl commands, use these placeholder values (user should provide actual values):
|
|
|
|
- `PROJECT_ID` - Use sample IDs like 15974631 or 15914808
|
|
- `ORG_ID` - From FILEVINE_ORG_ID env var
|
|
- `USER_ID` - From FILEVINE_USER_ID env var
|
|
- `BEARER_TOKEN` - From FilevineClient.get_bearer_token()
|
|
|
|
## Tips
|
|
|
|
1. Start with the most likely endpoints first
|
|
2. The sample data shows that many fields are duplicated across endpoints - check multiple places
|
|
3. Date fields are often in ISO format in API responses
|
|
4. Some forms (like `newFileReview`) contain multiple related date fields
|
|
5. Team roles use specific names - "Assigned Attorney", "Primary", "Secondary Paralegal"
|
|
6. Contact objects in arrays may have `personTypes` to identify their role
|
|
|
|
## Example Workflow
|
|
|
|
User: "What endpoint should I hit to find the matter number?"
|
|
|
|
1. Identify: User wants "matter number" field
|
|
2. Guess: Matter number might be in `Projects/{id}/Forms/matterOverview` based on sample data patterns
|
|
3. Check: `Projects/{id}` also has `number` field
|
|
4. Execute: curl to both endpoints with project 15974631
|
|
5. Report: Found `number` in project root and `matterNumber` in matterOverview form
|