canonical: https://jentic.com/apis/markifact.com/markifact

# Markifact API

The Markifact API manages the external account connections in a Markifact team workspace and reports what the team's workflows and agents have run and spent. Connections are created either from credentials you already hold, which Markifact verifies with the provider before storing, or through a shareable OAuth auth link whose status moves from pending to connected or expired. The same API returns the team's credit balance, a ledger of credit charges filterable by service_type, and operation logs filterable by source_type and status.

## For AI agents

Connect external accounts to a Markifact workspace with credentials or OAuth auth links, look up and delete connections, and read credit balance, credit charges, and operation logs.

## Scope

Does not build or run marketing workflows, publish ads, or send campaigns through this spec. Use for managing Markifact workspace connections, credits, and operation logs only.

## Capabilities

- List the connection types Markifact supports, with their auth methods and the credential fields each manual type expects
- Create a connection from existing credentials, verified with the provider before it is stored
- Generate a shareable OAuth auth link for an OAuth-only connection type and poll whether it is pending, connected, or expired
- Look up a connection by Markifact connection ID or by your own external_id using lookup_by
- Read the team's credit balance and page through credit charges by service_type, service_id, or user_id
- Page through operation logs filtered by source_type such as agent or workflow, status, operation_id, or source_run_id

## Use cases

### Client onboarding agent through Jentic

An agency assistant connects each new client's accounts to the Markifact workspace. Through Jentic it lists connection types, creates an auth link tagged with the client's external_id, sends it, and polls the link's status until it is connected. The Markifact bearer token is injected by Jentic at call time, so the agent never sees it.

Example prompt: GET `/v1/connections/types`, then POST `/v1/connections/auth-link` with connection_type set to the chosen type, external_id 'client-42', and redirect_url 'https://agency.example.com/done', and poll GET `/v1/connections/auth-links/{auth_link_id}/status` until it reports connected

### Connecting accounts from existing credentials

When the team already holds a provider credential, a connection can be created directly for any type whose auth_methods include manual. Markifact checks the credentials with the provider first, so a successful response means the connection works. OAuth-only types cannot be created this way and need an auth link instead.

Example prompt: POST `/v1/connections` with connection_type, name 'Client 42 account', and the credentials fields listed for that type by GET `/v1/connections/types`

### Credit spend reporting

Teams running Markifact workflows, agents, and copilot need to see where credits go. The credit balance call returns the current balance, and the credit log lists charges newest first, filterable by service_type, service_id, user_id, and a created_after and created_before window in Unix seconds.

Example prompt: GET `/v1/credits`, then GET `/v1/credits/logs` with service_type 'workflow' and created_after set to seven days ago, and total the charges per service_id

### Troubleshooting failed runs

When a workflow misbehaves, operation logs show what ran. Logs can be filtered by source_type, status such as error, operation_id, source_id, and source_run_id for a single workflow run, and one log can be fetched by ID for full detail.

Example prompt: GET `/v1/logs` with source_type 'workflow' and status 'error', then GET `/v1/logs/{log_id}` for the newest entry and summarise what failed

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/connections/types` | List connection types |
| POST | `/v1/connections` | Create a connection from credentials |
| POST | `/v1/connections/auth-link` | Create an OAuth auth link |
| GET | `/v1/connections/auth-links/{auth_link_id}/status` | Check auth link status |
| GET | `/v1/connections` | List connections |
| GET | `/v1/credits/logs` | List credit charges |
| GET | `/v1/logs` | List operation logs |

## Key resources

- **Connections** — List, create, look up, and delete workspace connections, and list supported connection types
- **Auth links** — Create shareable OAuth links and check whether they are pending, connected, or expired
- **Credits** — Read the credit balance and the ledger of credit charges
- **Logs** — List and fetch operation logs from agents, workflows, and other sources

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 65 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 83 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 49 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 64 / 100
- **View full report:** https://jentic.com/apis/markifact.com/markifact/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Markifact by hand means managing its bearer token, choosing between manual credentials and OAuth auth links per connection type, and paging logs with next_cursor. Through Jentic you install once, import the Markifact API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Markifact puts the connection id in the URL path (`/v1/connections/{connection_id}`), so a rule can limit your agent to one connection and the operations you pick for it. You choose the operations it may call, so destructive ones like connection deletion or credential-based connection creation are not included unless you add them.
- **Credential handling:** Your Markifact token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create an OAuth link to connect an account' or 'list failed workflow logs', and Jentic returns the matching Markifact operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Pipedream API** — Workflow automation platform with connected accounts for many APIs
- **Zapier AI Actions API** — Lets agents run Zapier actions across connected apps
- **Airbyte API** — Data movement between sources and destinations through connectors

## FAQ

### Is there a Markifact MCP server?

You don't need an MCP server to give your agent the Markifact API. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent calls it. Connection and log operations are found by intent when needed, so no extra tool definitions sit in the agent's context.

### What authentication does the Markifact API use?

Per its OpenAPI spec, the Markifact API authenticates with a bearer token in the Authorization header. Through Jentic the token is stored encrypted by your own Jentic One instance and injected at call time, so it never enters the agent's prompt or logs.

### What is the difference between creating a connection and creating an auth link?

POST `/v1/connections` takes credentials you already hold and works only for connection types whose auth_methods include manual; Markifact verifies them with the provider before storing. POST `/v1/connections/auth-link` creates a shareable OAuth link for OAuth types, and its status endpoint reports pending, connected, or expired.

### Can I limit what my agent is allowed to do with the Markifact API?

Yes. Write a rule that allows only GET `/v1/logs`, GET `/v1/logs/{log_id}`, and GET `/v1/credits/logs`, so a reporting agent can investigate runs and spend but cannot create or delete connections. Your own instance runs those calls.

### What are the rate limits for the Markifact API?

The OpenAPI spec does not specify rate limits. Check the Markifact documentation at https://docs.markifact.com for current limits.

### How do I send a client an OAuth connection link through Jentic?

Add the Markifact API to Jentic One from the directory and store your bearer token once. Your agent searches for 'create an OAuth link to connect an account', calls POST `/v1/connections/auth-link` with connection_type and an external_id, and later checks the link's status. To run it on your own infrastructure, install Jentic One from its GitHub repo.