Agent Skills: fireflies

Troubleshooting

If requests fail, run zero doctor check-connector --env-name FIREFLIES_TOKEN or zero doctor check-connector --url https://api.fireflies.ai/graphql --method POST

How to Use

All examples below assume you have FIREFLIES_TOKEN set.

Endpoint: https://api.fireflies.ai/graphql

The Fireflies API is GraphQL-based. All requests are POST to a single endpoint. Write the GraphQL query to /tmp/fireflies_request.json, then execute with curl.

1. Get Current User

Fetch details for the API key owner. Omit the userId variable to get the current user.

Write to /tmp/fireflies_request.json:

{
  "query": "query { user { user_id name email num_transcripts minutes_consumed is_admin integrations } }"
}

Then run:

curl -s -X POST "https://api.fireflies.ai/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $FIREFLIES_TOKEN" -d @/tmp/fireflies_request.json | jq '.data.user'

2. List Transcripts

Fetch a list of recent meeting transcripts.

Write to /tmp/fireflies_request.json:

{
  "query": "query { transcripts(limit: 10) { id title date duration organizer_email participants host_email } }"
}

Then run:

curl -s -X POST "https://api.fireflies.ai/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $FIREFLIES_TOKEN" -d @/tmp/fireflies_request.json | jq '.data.transcripts'

Search by Keyword

Write to /tmp/fireflies_request.json:

{
  "query": "query Transcripts($keyword: String) { transcripts(keyword: $keyword, limit: 10) { id title date duration } }",
  "variables": { "keyword": "product roadmap" }
}

Then run:

curl -s -X POST "https://api.fireflies.ai/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $FIREFLIES_TOKEN" -d @/tmp/fireflies_request.json | jq '.data.transcripts'

Filter by Date Range

Write to /tmp/fireflies_request.json:

{
  "query": "query Transcripts($fromDate: DateTime, $toDate: DateTime) { transcripts(fromDate: $fromDate, toDate: $toDate, limit: 20) { id title date duration } }",
  "variables": { "fromDate": "2025-01-01T00:00:00.000Z", "toDate": "2025-12-31T23:59:59.000Z" }
}

Then run:

curl -s -X POST "https://api.fireflies.ai/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $FIREFLIES_TOKEN" -d @/tmp/fireflies_request.json | jq '.data.transcripts'

Filter by Participant

Write to /tmp/fireflies_request.json:

{
  "query": "query Transcripts($participants: [String]) { transcripts(participants: $participants, limit: 10) { id title date participants } }",
  "variables": { "participants": ["alice@example.com"] }
}

Then run:

curl -s -X POST "https://api.fireflies.ai/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $FIREFLIES_TOKEN" -d @/tmp/fireflies_request.json | jq '.data.transcripts'

Transcripts Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | keyword | String | Search in title and spoken words (max 255 chars) | | fromDate / toDate | DateTime | ISO 8601 date range filter | | host_email | String | Filter by host email | | organizers | [String] | Filter by organizer emails | | participants | [String] | Filter by participant emails | | mine | Boolean | Only meetings owned by API key owner | | limit | Int | Max results (default 50) | | skip | Int | Pagination offset |

3. Get Single Transcript

Fetch full details for a specific transcript.

Basic Info

Write to /tmp/fireflies_request.json:

{
  "query": "query Transcript($transcriptId: String!) { transcript(id: $transcriptId) { id title date duration host_email organizer_email participants transcript_url audio_url } }",
  "variables": { "transcriptId": "your_transcript_id" }
}

Then run:

curl -s -X POST "https://api.fireflies.ai/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $FIREFLIES_TOKEN" -d @/tmp/fireflies_request.json | jq '.data.transcript'

With Summary and Action Items

Write to /tmp/fireflies_request.json:

{
  "query": "query Transcript($transcriptId: String!) { transcript(id: $transcriptId) { id title summary { keywords action_items outline overview short_summary topics_discussed } } }",
  "variables": { "transcriptId": "your_transcript_id" }
}

Then run:

curl -s -X POST "https://api.fireflies.ai/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $FIREFLIES_TOKEN" -d @/tmp/fireflies_request.json | jq '.data.transcript.summary'

With Sentences (Full Transcript)

Write to /tmp/fireflies_request.json:

{
  "query": "query Transcript($transcriptId: String!) { transcript(id: $transcriptId) { id title sentences { index speaker_name text start_time end_time } } }",
  "variables": { "transcriptId": "your_transcript_id" }
}

Then run:

curl -s -X POST "https://api.fireflies.ai/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $FIREFLIES_TOKEN" -d @/tmp/fireflies_request.json | jq '.data.transcript.sentences'

With Analytics

Write to /tmp/fireflies_request.json:

{
  "query": "query Transcript($transcriptId: String!) { transcript(id: $transcriptId) { id title analytics { sentiments { negative_pct neutral_pct positive_pct } speakers { name duration word_count words_per_minute questions filler_words } } } }",
  "variables": { "transcriptId": "your_transcript_id" }
}

Then run:

curl -s -X POST "https://api.fireflies.ai/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $FIREFLIES_TOKEN" -d @/tmp/fireflies_request.json | jq '.data.transcript.analytics'

4. Upload Audio for Transcription

Upload an audio file URL for Fireflies to transcribe. The file must be publicly accessible via HTTPS. Supported formats: mp3, mp4, wav, m4a, ogg.

Write to /tmp/fireflies_request.json:

{
  "query": "mutation($input: AudioUploadInput) { uploadAudio(input: $input) { success title message } }",
  "variables": {
    "input": {
      "url": "https://example.com/meeting-recording.mp3",
      "title": "Team Standup 2025-01-15"
    }
  }
}

Then run:

curl -s -X POST "https://api.fireflies.ai/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $FIREFLIES_TOKEN" -d @/tmp/fireflies_request.json | jq '.data.uploadAudio'

Upload with Attendees

Write to /tmp/fireflies_request.json:

{
  "query": "mutation($input: AudioUploadInput) { uploadAudio(input: $input) { success title message } }",
  "variables": {
    "input": {
      "url": "https://example.com/meeting-recording.mp3",
      "title": "Product Review",
      "attendees": [
        { "displayName": "Alice", "email": "alice@example.com" },
        { "displayName": "Bob", "email": "bob@example.com" }
      ]
    }
  }
}

Then run:

curl -s -X POST "https://api.fireflies.ai/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $FIREFLIES_TOKEN" -d @/tmp/fireflies_request.json | jq '.data.uploadAudio'

Upload Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | url | String | Public HTTPS URL of audio/video file (required) | | title | String | Title for the meeting | | attendees | [Object] | Array of { displayName, email, phoneNumber } | | webhook | String | URL to notify when transcription completes | | custom_language | String | Language code (e.g., es, de, ja) | | save_video | Boolean | Retain video file | | client_reference_id | String | Custom identifier for the upload |

5. List Team Users

Fetch all users in the team.

Write to /tmp/fireflies_request.json:

{
  "query": "query { users { user_id name email is_admin num_transcripts minutes_consumed } }"
}

Then run:

curl -s -X POST "https://api.fireflies.ai/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $FIREFLIES_TOKEN" -d @/tmp/fireflies_request.json | jq '.data.users'

Guidelines

1. GraphQL single endpoint: All requests go to POST https://api.fireflies.ai/graphql with the query in the JSON body
2. Request only needed fields: GraphQL lets you specify exactly which fields to return; keep queries minimal for better performance
3. Pagination: Use limit and skip parameters on the transcripts query. Maximum limit is 50
4. Date format: Use ISO 8601 format for fromDate and toDate (e.g., 2025-01-01T00:00:00.000Z)
5. Audio uploads are async: After uploading, the transcription is queued. Use webhooks or poll the transcripts list to check completion
6. File requirements: Uploaded audio must be a valid HTTPS URL and publicly accessible. Supported formats: mp3, mp4, wav, m4a, ogg
7. Check for errors: GraphQL errors appear in the errors array of the response, not in HTTP status codes