Skip to main content

Harness GraphQL API FAQs

This article addresses some frequently asked questions about Harness GraphQL APIs.

Before You Begin​

General​

Why Harness uses GraphQL APIs?​

GraphQL offers the following efficiency and reliability features for your consuming applications:

  • Scoping – Each request can query for all the resources and data you want, and only the data you want.
  • Introspection – Your client applications can query the API schema for details about the API.
  • Hierarchical Organization – Your queries' nested fields mirror the organization of the JSON data that the queries return.
  • Strong Typing – Applications can specify expected data types per field, and receive clear and specific error notifications.
  • Future-Proofing – GraphQL allows us to incrementally expose new fields and types, and retire obsolete fields, without versioning the API or breaking your existing queries.

Where do I construct API queries and see responses?​

The Harness API Explorer allows you to construct and perform API queries and see their responses. You can use API Explorer to examine the API's structure, to build and test queries against your data, and to optimize your queries. For more information, see Harness API Explorer.

How do I fetch data using GraphQL APIs?​

Every GraphQL schema has a root type for both queries and mutations. The query type defines GraphQL operations that retrieve data from the server. GraphQL queries return only the data you specify. To form a query, you must specify fields within fields (also known as nested subfields).

Here is an example:

query {  
  applicationByName(name: "Harness GraphQL"){  
    id  
    name  
  }  
}

For more information, see Queries and Schema and Types.

How do I write data using GraphQL APIs?​

Every GraphQL schema has a root type for both queries and mutations. The mutation type defines GraphQL operations that change data on the server. It is analogous to performing HTTP verbs such as POST, PATCH, and DELETE.

There are generally three kinds of mutations:

  • creating new data
  • updating existing data
  • deleting existing data

Mutations follow the same syntactical structure as queries, but they always need to start with the mutation keyword. 

Here is an example:

mutation createapp($app: CreateApplicationInput!) {  
  createApplication(input: $app) {  
    clientMutationId  
    application {  
      name  
      id  
    }  
  }  
}

For more information, see Mutations and Schema and Types.

Is clientMutationId a mandatory parameter?​

No. This is a unique identifier (string) for the client performing the mutation.clientMutationId appears in both input and output types for mutations. If present, the same value is intended to be returned in the response as well. The client can use this to indicate duplicate mutation requests to the server and avoid multiple updates for the same request.

How does Harness GraphQL API factor dynamic values out of the query?​

GraphQL has a first-class way to factor dynamic values out of the query, and pass them as a separate dictionary. These values are called variables.

Here is an example:

query($thisPipeline: String!) {  
  pipeline(pipelineId: $thisPipeline) {  
    id  
    name  
    description  
  }  
}

Does Harness impose Rate/Data Limiting?​

Yes. Harness GraphQL API imposes the following limits:

  • Deployments: 100 per 24 hours (rolling, not reset at 12am).
  • GraphQL: 30 requests per minute.
  • GraphQL custom dashboard: 30 requests per minute per paid account, 5 per Community and Essentials Editions.
  • Delegate: 200 tasks acquired per minute per account. 10000 tasks acquired per minute per pod.
  • Export Executions: 25 exports per 24 hours (rolling).
  • Logins: 300 request per minute per pod.
Cloudflare Rate Limiting​

Harness uses Cloudflare as part of its platform. As a result, the following limitations apply:

  • 500 queries per minute per Harness account Id.
  • If the limit is reached, queries are blocked for one minute.

If the limit is reached, you will see a 429 status code with the following response:

{  
  "code": "TOO_MANY_REQUESTS",  
  "message": "Too many requests received, please try again later - Rate-Limit Limit 500 reached",  
  "status": "Error"  
}

What does API in beta mean?​

API in beta allows you to try out new APIs and changes to the existing API methods before they become part of the official Harness GraphQL API. During the beta phase, some changes might be made to the features based on the feedback.

Where can I find a list of deprecated API features?​

See Deprecated API Features.

How do I share any feedback on Harness GraphQL APIs?​

You can send us feedback on our APIs at api-feedback@harness.io. We'd love to hear from you.

Building Applications Using Postman​

Can I query Harness GraphQL in Postman?​

Yes. See Query Harness GraphQL in Postman.

How do I convert my query into the programming language of my choice in Postman?​

See Build Language-Specific Queries in Postman.

Authentication​

How do I authenticate in Harness API Explorer?​

You can authenticate using the Logged-in User Session or Use API Key. The authentication determines what data you can query and retrieve via the API. By default, when you launch the API Explorer, you authenticate using a session key. See Harness API Explorer.

Cloud Provider APIs​

Can I create, read, update, and delete Harness Cloud Providers using Harness GraphQL APIs?​

Yes, you can create, read, update, and delete Harness Cloud Providers using the Harness API. See Use Cloud Providers API.

How to search for Cloud Provider by ID?​

Using the Cloud Providers ID, you can run cloudProvider(cloudProviderId) or cloudProviderById(). See Search for Cloud Provider by ID.

Can I find all Cloud Providers by type using Harness API?​

Yes. For more information, see Find all Cloud Providers by Type.

How to find Cloud Provider by name?​

Using the Cloud Provider's name, run cloudProviderByName. See Find Cloud Provider by Name.

Artifact Source APIs​

Can I fetch Artifact Source details using GraphQL APIs?​

Yes. For details, see Fetch Artifact Source Details Using GraphQL APIs.

How to fetch Artifact Source from a Service using APIs?​

Use this sample query to get the Artifact Source and Artifact History from a Harness Service. Provide a Service ID to fetch the details.

query{  
  service(serviceId: "ABEvYYxdRSegoaSFxIx2xX"){  
    artifactSources{  
      id  
      name  
      artifacts(limit:10, offset:0){  
        nodes {  
          id  
          buildNo  
        }  
      }  
    }  
  }  
}

What is the query used to fetch Artifact Source ID from an Artifact?​

{  
  artifacts(filters:[  
    {  
      artifact: {  
        operator: EQUALS,  
        values: ["a9xxxABCDwCNxnk90as1fA"]  
      }  
    }  
  ], limit:10, offset:0){  
    nodes {  
      id  
      artifactSource {  
        id  
      }  
      buildNo  
    }  
  }  
}

Artifact Type APIs​

Can I fetch Artifact Type details using GraphQL APIs?​

Yes. See Fetch Artifact Type Details Using GraphQL APIs.

What are the supported Artifact Types?​

You can fetch the following Artifact Type details using GraphQL APIs. For more information, see the following topics:

Harness Applications API​

What are the different actions that I can perform using Harness Applications API?​

You can perform the following actions using Harness Application APIs:

For more information, see Use Harness Applications API.

How do I use API to retrieve IDs by name?​

You can retrieve applicationId, userIds, and userGroupId object IDs (respectively) by using the applicationByName, userByName, and userGroupByName operations. Each of these queries takes a required name argument, as a string. See Use API to Retrieve IDs by Name.

Workflow APIs​

Can I get Workflow details using GraphQL APIs?​

Yes, you can get Workflow information using APIs.

How to see executions for a given Workflow using Harness APIs?​

This sample queries by workflowId to return up to 30 deployments.

{  
  executions(  
    filters: [  
      { workflow: { operator: EQUALS, values: ["<workflowId>"] } }   
    ]  
    limit: 30  
  ) {  
    pageInfo {  
      total  
    }  
    nodes {  
      id  
    }  
  }  
}

How can I trigger a Workflow using GraphQL API?​

Perform the following steps:

For details, see Trigger Workflows or Pipelines Using GraphQL API.

Can I fetch a user by email address using the Harness API?​

Yes, you can fetch a user by email address using the Harness API, including users that have not accepted invites. See Fetch Users By Email Address.

Pipeline APIs​

What is the query used to fetch Pipeline ID?​

Use this query to get pipelineId .

query{pipelineByName(applicationId: "-XXXXqR6QIeXXXz-VuwIzA" pipelineName: "Test Pipeline"  
) {  
  id  
}}

Can I see details of a Pipeline using Harness API?​

Yes. This example returns basic information about a specified Pipeline. It corresponds to a GET operation in a REST API.

{  
  pipeline(pipelineId: "<pipelineId>") {  
    id  
    name  
    description  
  }  
}

For more information, see Use Pipelines API.

Service APIs​

How to fetch the list of Services for a given Application using Services API?​

This sample queries by applicationId to return id and name values for up to 1,000 Services.

{  
  services(  
    filters: [  
      { application: { operator: EQUALS, values: ["<applicationId>"] } }  
    ]  
    limit: 1000  
  ) {  
    pageInfo {  
      total  
    }  
    nodes {  
      id  
      name  
    }  
  }  
}

For more information, see Use Services API.

Trigger APIs​

How to create, read, update, and delete Triggers using the Harness API?​

Triggers automate deployments using a variety of conditions, such as Git events, new Artifacts, schedules, and the success of other Pipelines.

  • Create a Trigger using the mutation createTrigger. You can select any of the following conditions to execute a Trigger:
    • On Pipeline Completion
    • On New Artifact
    • On Time Schedule
    • On Webhook Event
  • Update a Trigger using the mutation updateTrigger.
  • Delete a Trigger using the mutation deleteTrigger. You need to enter the ID of the Trigger that you want to delete

See Use Trigger APIs.

Users and Groups API​

Can I create a user and assign them to the Harness User Groups?​

Yes. See Create a user.

How to assign permissions to Harness user groups using APIs?​

For details, see Assign Permissions.

How do I use API to retrieve IDs by name?​

You can retrieve applicationId, userIds, and userGroupId object IDs (respectively) by using the applicationByName, userByName, and userGroupByName operations. Each of these queries takes a required name argument, as a string. See Use API to Retrieve IDs by Name.

Harness Tags​

How do I filter Harness entities using Harness Tags?​

Harness provides advanced tagging features for all of your Harness Application entities (Services, Environments, Workflows, etc), as described in Assign Metadata Using Tags and Apply Filters Using Tags.

You can use Tags to search for entities, ensuring that you only return the entities tagged with a specific name and value. Perform the following steps:

  1. Assign Tags to your Harness Entities.
  2. Use TagFilter.

For details, see Filter Harness Entities using Harness Tags in the API.

Secrets Management​

What are the different secret types supported using API?​

Harness GraphQL API includes:

Git Connectors​

Can I create, read, update, and delete (CRUD) Git Connectors using Harness GraphQL API?​

Yes. For more information, see Add Git Connectors Using API.