# Send Tally to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "tally-api",
    "name": "Tally",
    "source": "tencent",
    "type": "skill",
    "category": "效率提升",
    "sourceUrl": "https://clawhub.ai/byungkyu/tally-api",
    "canonicalUrl": "https://clawhub.ai/byungkyu/tally-api",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/tally-api",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=tally-api",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "SKILL.md",
      "LICENSE.txt"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "tally-api",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-01T09:55:38.962Z",
      "expiresAt": "2026-05-08T09:55:38.962Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=tally-api",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=tally-api",
        "contentDisposition": "attachment; filename=\"tally-api-1.0.3.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "tally-api"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/tally-api"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/tally-api",
    "downloadUrl": "https://openagent3.xyz/downloads/tally-api",
    "agentUrl": "https://openagent3.xyz/skills/tally-api/agent",
    "manifestUrl": "https://openagent3.xyz/skills/tally-api/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/tally-api/agent.md"
  }
}
```
## Documentation

### Tally

Access the Tally API with managed OAuth authentication. Manage forms, submissions, workspaces, and webhooks for your Tally account.

### Quick Start

# List your forms
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/tally/forms')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('User-Agent', 'Maton/1.0')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

### Base URL

https://gateway.maton.ai/tally/{native-api-path}

Replace {native-api-path} with the actual Tally API endpoint path. The gateway proxies requests to api.tally.so and automatically injects your OAuth token.

### Authentication

All requests require the Maton API key in the Authorization header and the User Agent header:

Authorization: Bearer $MATON_API_KEY
User-Agent: Maton/1.0

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

### Getting Your API Key

Sign in or create an account at maton.ai
Go to maton.ai/settings
Copy your API key

### Connection Management

Manage your Tally OAuth connections at https://ctrl.maton.ai.

### List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=tally&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

### Create Connection

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'tally'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

### Get Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "connection": {
    "connection_id": "cd54e2b0-f1d0-435e-a97d-f2d6a5c474bf",
    "status": "ACTIVE",
    "creation_time": "2026-02-07T21:00:31.222600Z",
    "last_updated_time": "2026-02-07T21:00:37.821240Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "tally",
    "metadata": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

### Delete Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

### Specifying Connection

If you have multiple Tally connections, specify which one to use with the Maton-Connection header:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/tally/forms')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', 'cd54e2b0-f1d0-435e-a97d-f2d6a5c474bf')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If omitted, the gateway uses the default (oldest) active connection.

### User

Get Current User

GET /tally/users/me

Response:

{
  "id": "w2lBkb",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "organizationId": "n0Ze8Q",
  "subscriptionPlan": "FREE",
  "createdAt": "2026-02-07T20:58:54.000Z",
  "updatedAt": "2026-02-07T22:50:35.000Z"
}

### Forms

List Forms

GET /tally/forms

Query Parameters:

page - Page number (default: 1)
limit - Items per page (default: 50)

Response:

{
  "items": [
    {
      "id": "GxdRaQ",
      "name": "Contact Form",
      "workspaceId": "3jW9Q1",
      "organizationId": "n0Ze8Q",
      "status": "PUBLISHED",
      "hasDraftBlocks": false,
      "numberOfSubmissions": 42,
      "createdAt": "2026-02-09T08:36:00.000Z",
      "updatedAt": "2026-02-09T08:36:17.000Z",
      "isClosed": false
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 1,
  "hasMore": false
}

Get Form

GET /tally/forms/{formId}

Response:

{
  "id": "GxdRaQ",
  "name": "Contact Form",
  "workspaceId": "3jW9Q1",
  "status": "PUBLISHED",
  "blocks": [
    {
      "uuid": "11111111-1111-1111-1111-111111111111",
      "type": "FORM_TITLE",
      "groupUuid": "22222222-2222-2222-2222-222222222222",
      "groupType": "FORM_TITLE",
      "payload": {}
    },
    {
      "uuid": "33333333-3333-3333-3333-333333333333",
      "type": "INPUT_TEXT",
      "groupUuid": "44444444-4444-4444-4444-444444444444",
      "groupType": "INPUT_TEXT",
      "payload": {}
    }
  ],
  "settings": null
}

Create Form

POST /tally/forms
Content-Type: application/json

{
  "status": "DRAFT",
  "workspaceId": "3jW9Q1",
  "blocks": [
    {
      "type": "FORM_TITLE",
      "uuid": "11111111-1111-1111-1111-111111111111",
      "groupUuid": "22222222-2222-2222-2222-222222222222",
      "groupType": "FORM_TITLE",
      "title": "My Form",
      "payload": {}
    },
    {
      "type": "INPUT_TEXT",
      "uuid": "33333333-3333-3333-3333-333333333333",
      "groupUuid": "44444444-4444-4444-4444-444444444444",
      "groupType": "INPUT_TEXT",
      "title": "Your name",
      "payload": {}
    }
  ]
}

Block Types:

FORM_TITLE - Form title block
INPUT_TEXT - Single-line text input
INPUT_EMAIL - Email input
INPUT_NUMBER - Number input
INPUT_PHONE_NUMBER - Phone number input
INPUT_DATE - Date picker
INPUT_TIME - Time picker
INPUT_LINK - URL input
TEXTAREA - Multi-line text input
MULTIPLE_CHOICE - Radio buttons
CHECKBOXES - Checkbox group
DROPDOWN - Dropdown select
LINEAR_SCALE - Scale rating
RATING - Star rating
FILE_UPLOAD - File upload
SIGNATURE - Signature field
PAYMENT - Payment field
HIDDEN_FIELDS - Hidden fields

Note: Block uuid and groupUuid must be valid UUIDs (GUIDs).

Update Form

PATCH /tally/forms/{formId}
Content-Type: application/json

{
  "name": "Updated Form Name",
  "status": "PUBLISHED"
}

Status Values:

DRAFT - Form is a draft
PUBLISHED - Form is live

Delete Form

DELETE /tally/forms/{formId}

Moves the form to trash.

### Form Questions

List Questions

GET /tally/forms/{formId}/questions

Response:

{
  "questions": [
    {
      "uuid": "33333333-3333-3333-3333-333333333333",
      "type": "INPUT_TEXT",
      "title": "Your name"
    }
  ],
  "hasResponses": true
}

### Form Submissions

List Submissions

GET /tally/forms/{formId}/submissions

Query Parameters:

page - Page number (default: 1)
limit - Items per page (default: 50)
startDate - Filter by start date (ISO 8601)
endDate - Filter by end date (ISO 8601)
afterId - Get submissions after this ID (cursor pagination)

Response:

{
  "page": 1,
  "limit": 50,
  "hasMore": false,
  "totalNumberOfSubmissionsPerFilter": {
    "all": 42,
    "completed": 40,
    "partial": 2
  },
  "questions": [
    {
      "uuid": "33333333-3333-3333-3333-333333333333",
      "type": "INPUT_TEXT",
      "title": "Your name"
    }
  ],
  "submissions": [
    {
      "id": "sub123",
      "respondentId": "resp456",
      "formId": "GxdRaQ",
      "createdAt": "2026-02-09T10:00:00.000Z",
      "isCompleted": true,
      "responses": [
        {
          "questionId": "33333333-3333-3333-3333-333333333333",
          "value": "John Doe"
        }
      ]
    }
  ]
}

Get Submission

GET /tally/forms/{formId}/submissions/{submissionId}

Delete Submission

DELETE /tally/forms/{formId}/submissions/{submissionId}

### Workspaces

List Workspaces

GET /tally/workspaces

Response:

{
  "items": [
    {
      "id": "3jW9Q1",
      "name": "My Workspace",
      "createdByUserId": "w2lBkb",
      "createdAt": "2026-02-09T08:35:53.000Z",
      "updatedAt": "2026-02-09T08:35:53.000Z"
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 1,
  "hasMore": false
}

Get Workspace

GET /tally/workspaces/{workspaceId}

Response:

{
  "id": "3jW9Q1",
  "name": "My Workspace",
  "createdByUserId": "w2lBkb",
  "createdAt": "2026-02-09T08:35:53.000Z",
  "members": [
    {
      "id": "w2lBkb",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com"
    }
  ]
}

Create Workspace

POST /tally/workspaces
Content-Type: application/json

{
  "name": "New Workspace"
}

Note: Creating workspaces requires a Pro subscription.

Update Workspace

PATCH /tally/workspaces/{workspaceId}
Content-Type: application/json

{
  "name": "Updated Workspace Name"
}

Delete Workspace

DELETE /tally/workspaces/{workspaceId}

Moves the workspace and all its forms to trash.

### Organization Users

List Users

GET /tally/organizations/{organizationId}/users

Response:

[
  {
    "id": "w2lBkb",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "createdAt": "2026-02-07T20:58:54.000Z"
  }
]

Remove User

DELETE /tally/organizations/{organizationId}/users/{userId}

### Organization Invites

List Invites

GET /tally/organizations/{organizationId}/invites

Create Invite

POST /tally/organizations/{organizationId}/invites
Content-Type: application/json

{
  "email": "newuser@example.com",
  "workspaceIds": ["3jW9Q1"]
}

Cancel Invite

DELETE /tally/organizations/{organizationId}/invites/{inviteId}

### Webhooks

List Webhooks

GET /tally/webhooks

Note: Listing webhooks may require specific permissions.

Create Webhook

POST /tally/webhooks
Content-Type: application/json

{
  "formId": "GxdRaQ",
  "url": "https://your-endpoint.com/webhook",
  "eventTypes": ["FORM_RESPONSE"]
}

Webhook Event Types:

FORM_RESPONSE - Triggered when a new form response is submitted

Update Webhook

PATCH /tally/webhooks/{webhookId}
Content-Type: application/json

{
  "url": "https://new-endpoint.com/webhook"
}

Delete Webhook

DELETE /tally/webhooks/{webhookId}

List Webhook Events

GET /tally/webhooks/{webhookId}/events

Retry Webhook Event

POST /tally/webhooks/{webhookId}/events/{eventId}

### Pagination

Tally uses page-based pagination:

GET /tally/forms?page=1&limit=50

Response includes pagination info:

{
  "items": [...],
  "page": 1,
  "limit": 50,
  "total": 100,
  "hasMore": true
}

For submissions, cursor-based pagination is also available using afterId.

### JavaScript

const response = await fetch(
  'https://gateway.maton.ai/tally/forms',
  {
    headers: {
      'Authorization': \`Bearer ${process.env.MATON_API_KEY}\`,
      'User-Agent': 'Maton/1.0'
    }
  }
);
const data = await response.json();
console.log(data.items);

### Python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/tally/forms',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'User-Agent': 'Maton/1.0'
    }
)
data = response.json()
print(data['items'])

### Create Form and Get Submissions

import os
import requests
import uuid

headers = {
    'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
    'User-Agent': 'Maton/1.0'
}

# Create a simple form
form_data = {
    'status': 'DRAFT',
    'blocks': [
        {
            'type': 'FORM_TITLE',
            'uuid': str(uuid.uuid4()),
            'groupUuid': str(uuid.uuid4()),
            'groupType': 'FORM_TITLE',
            'title': 'Contact Form',
            'payload': {}
        },
        {
            'type': 'INPUT_EMAIL',
            'uuid': str(uuid.uuid4()),
            'groupUuid': str(uuid.uuid4()),
            'groupType': 'INPUT_EMAIL',
            'title': 'Your email',
            'payload': {}
        }
    ]
}

response = requests.post(
    'https://gateway.maton.ai/tally/forms',
    headers=headers,
    json=form_data
)
form = response.json()
print(f"Created form: {form['id']}")

# Get submissions for a form
response = requests.get(
    f'https://gateway.maton.ai/tally/forms/{form["id"]}/submissions',
    headers=headers
)
submissions = response.json()
print(f"Total submissions: {submissions['totalNumberOfSubmissionsPerFilter']['all']}")

### Notes

Form and workspace IDs are short alphanumeric strings (e.g., GxdRaQ)
Block uuid and groupUuid fields must be valid UUIDs (GUIDs)
Creating workspaces requires a Pro subscription
The API is in public beta and subject to changes
Rate limit: 100 requests per minute
Use webhooks instead of polling for real-time submission notifications
IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

### Error Handling

StatusMeaning400Missing Tally connection or validation error401Invalid or missing Maton API key403Insufficient permissions404Resource not found429Rate limited (100 req/min)4xx/5xxPassthrough error from Tally API

### Troubleshooting: API Key Issues

Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

Verify the API key is valid by listing connections:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

### Troubleshooting: Invalid App Name

Ensure your URL path starts with tally. For example:

Correct: https://gateway.maton.ai/tally/forms
Incorrect: https://gateway.maton.ai/forms

### Resources

Tally API Introduction
Tally API Reference
Tally Help Center
Maton Community
Maton Support
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: byungkyu
- Version: 1.0.2
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-05-01T09:55:38.962Z
- Expires at: 2026-05-08T09:55:38.962Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/tally-api)
- [Send to Agent page](https://openagent3.xyz/skills/tally-api/agent)
- [JSON manifest](https://openagent3.xyz/skills/tally-api/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/tally-api/agent.md)
- [Download page](https://openagent3.xyz/downloads/tally-api)